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 1.4.6.@* 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 , Sep 24, 2018 25 26AdaCore 27 28Copyright @copyright{} 2008-2019, 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* Obsolescent Features:: 83* Compatibility and Porting Guide:: 84* GNU Free Documentation License:: 85* Index:: 86 87@detailmenu 88 --- The Detailed Node Listing --- 89 90About This Guide 91 92* What This Reference Manual Contains:: 93* Conventions:: 94* Related Information:: 95 96Implementation Defined Pragmas 97 98* Pragma Abort_Defer:: 99* Pragma Abstract_State:: 100* Pragma Acc_Parallel:: 101* Pragma Acc_Loop:: 102* Pragma Acc_Kernels:: 103* Pragma Acc_Data:: 104* Pragma Ada_83:: 105* Pragma Ada_95:: 106* Pragma Ada_05:: 107* Pragma Ada_2005:: 108* Pragma Ada_12:: 109* Pragma Ada_2012:: 110* Pragma Allow_Integer_Address:: 111* Pragma Annotate:: 112* Pragma Assert:: 113* Pragma Assert_And_Cut:: 114* Pragma Assertion_Policy:: 115* Pragma Assume:: 116* Pragma Assume_No_Invalid_Values:: 117* Pragma Async_Readers:: 118* Pragma Async_Writers:: 119* Pragma Attribute_Definition:: 120* Pragma C_Pass_By_Copy:: 121* Pragma Check:: 122* Pragma Check_Float_Overflow:: 123* Pragma Check_Name:: 124* Pragma Check_Policy:: 125* Pragma Comment:: 126* Pragma Common_Object:: 127* Pragma Compile_Time_Error:: 128* Pragma Compile_Time_Warning:: 129* Pragma Compiler_Unit:: 130* Pragma Compiler_Unit_Warning:: 131* Pragma Complete_Representation:: 132* Pragma Complex_Representation:: 133* Pragma Component_Alignment:: 134* Pragma Constant_After_Elaboration:: 135* Pragma Contract_Cases:: 136* Pragma Convention_Identifier:: 137* Pragma CPP_Class:: 138* Pragma CPP_Constructor:: 139* Pragma CPP_Virtual:: 140* Pragma CPP_Vtable:: 141* Pragma CPU:: 142* Pragma Deadline_Floor:: 143* Pragma Default_Initial_Condition:: 144* Pragma Debug:: 145* Pragma Debug_Policy:: 146* Pragma Default_Scalar_Storage_Order:: 147* Pragma Default_Storage_Pool:: 148* Pragma Depends:: 149* Pragma Detect_Blocking:: 150* Pragma Disable_Atomic_Synchronization:: 151* Pragma Dispatching_Domain:: 152* Pragma Effective_Reads:: 153* Pragma Effective_Writes:: 154* Pragma Elaboration_Checks:: 155* Pragma Eliminate:: 156* Pragma Enable_Atomic_Synchronization:: 157* Pragma Export_Function:: 158* Pragma Export_Object:: 159* Pragma Export_Procedure:: 160* Pragma Export_Value:: 161* Pragma Export_Valued_Procedure:: 162* Pragma Extend_System:: 163* Pragma Extensions_Allowed:: 164* Pragma Extensions_Visible:: 165* Pragma External:: 166* Pragma External_Name_Casing:: 167* Pragma Fast_Math:: 168* Pragma Favor_Top_Level:: 169* Pragma Finalize_Storage_Only:: 170* Pragma Float_Representation:: 171* Pragma Ghost:: 172* Pragma Global:: 173* Pragma Ident:: 174* Pragma Ignore_Pragma:: 175* Pragma Implementation_Defined:: 176* Pragma Implemented:: 177* Pragma Implicit_Packing:: 178* Pragma Import_Function:: 179* Pragma Import_Object:: 180* Pragma Import_Procedure:: 181* Pragma Import_Valued_Procedure:: 182* Pragma Independent:: 183* Pragma Independent_Components:: 184* Pragma Initial_Condition:: 185* Pragma Initialize_Scalars:: 186* Pragma Initializes:: 187* Pragma Inline_Always:: 188* Pragma Inline_Generic:: 189* Pragma Interface:: 190* Pragma Interface_Name:: 191* Pragma Interrupt_Handler:: 192* Pragma Interrupt_State:: 193* Pragma Invariant:: 194* Pragma Keep_Names:: 195* Pragma License:: 196* Pragma Link_With:: 197* Pragma Linker_Alias:: 198* Pragma Linker_Constructor:: 199* Pragma Linker_Destructor:: 200* Pragma Linker_Section:: 201* Pragma Lock_Free:: 202* Pragma Loop_Invariant:: 203* Pragma Loop_Optimize:: 204* Pragma Loop_Variant:: 205* Pragma Machine_Attribute:: 206* Pragma Main:: 207* Pragma Main_Storage:: 208* Pragma Max_Queue_Length:: 209* Pragma No_Body:: 210* Pragma No_Component_Reordering:: 211* Pragma No_Elaboration_Code_All:: 212* Pragma No_Heap_Finalization:: 213* Pragma No_Inline:: 214* Pragma No_Return:: 215* Pragma No_Run_Time:: 216* Pragma No_Strict_Aliasing:: 217* Pragma No_Tagged_Streams:: 218* Pragma Normalize_Scalars:: 219* Pragma Obsolescent:: 220* Pragma Optimize_Alignment:: 221* Pragma Ordered:: 222* Pragma Overflow_Mode:: 223* Pragma Overriding_Renamings:: 224* Pragma Partition_Elaboration_Policy:: 225* Pragma Part_Of:: 226* Pragma Passive:: 227* Pragma Persistent_BSS:: 228* Pragma Polling:: 229* Pragma Post:: 230* Pragma Postcondition:: 231* Pragma Post_Class:: 232* Pragma Rename_Pragma:: 233* Pragma Pre:: 234* Pragma Precondition:: 235* Pragma Predicate:: 236* Pragma Predicate_Failure:: 237* Pragma Preelaborable_Initialization:: 238* Pragma Prefix_Exception_Messages:: 239* Pragma Pre_Class:: 240* Pragma Priority_Specific_Dispatching:: 241* Pragma Profile:: 242* Pragma Profile_Warnings:: 243* Pragma Propagate_Exceptions:: 244* Pragma Provide_Shift_Operators:: 245* Pragma Psect_Object:: 246* Pragma Pure_Function:: 247* Pragma Rational:: 248* Pragma Ravenscar:: 249* Pragma Refined_Depends:: 250* Pragma Refined_Global:: 251* Pragma Refined_Post:: 252* Pragma Refined_State:: 253* Pragma Relative_Deadline:: 254* Pragma Remote_Access_Type:: 255* Pragma Restricted_Run_Time:: 256* Pragma Restriction_Warnings:: 257* Pragma Reviewable:: 258* Pragma Secondary_Stack_Size:: 259* Pragma Share_Generic:: 260* Pragma Shared:: 261* Pragma Short_Circuit_And_Or:: 262* Pragma Short_Descriptors:: 263* Pragma Simple_Storage_Pool_Type:: 264* Pragma Source_File_Name:: 265* Pragma Source_File_Name_Project:: 266* Pragma Source_Reference:: 267* Pragma SPARK_Mode:: 268* Pragma Static_Elaboration_Desired:: 269* Pragma Stream_Convert:: 270* Pragma Style_Checks:: 271* Pragma Subtitle:: 272* Pragma Suppress:: 273* Pragma Suppress_All:: 274* Pragma Suppress_Debug_Info:: 275* Pragma Suppress_Exception_Locations:: 276* Pragma Suppress_Initialization:: 277* Pragma Task_Name:: 278* Pragma Task_Storage:: 279* Pragma Test_Case:: 280* Pragma Thread_Local_Storage:: 281* Pragma Time_Slice:: 282* Pragma Title:: 283* Pragma Type_Invariant:: 284* Pragma Type_Invariant_Class:: 285* Pragma Unchecked_Union:: 286* Pragma Unevaluated_Use_Of_Old:: 287* Pragma Unimplemented_Unit:: 288* Pragma Universal_Aliasing:: 289* Pragma Universal_Data:: 290* Pragma Unmodified:: 291* Pragma Unreferenced:: 292* Pragma Unreferenced_Objects:: 293* Pragma Unreserve_All_Interrupts:: 294* Pragma Unsuppress:: 295* Pragma Use_VADS_Size:: 296* Pragma Unused:: 297* Pragma Validity_Checks:: 298* Pragma Volatile:: 299* Pragma Volatile_Full_Access:: 300* Pragma Volatile_Function:: 301* Pragma Warning_As_Error:: 302* Pragma Warnings:: 303* Pragma Weak_External:: 304* Pragma Wide_Character_Encoding:: 305 306Implementation Defined Aspects 307 308* Aspect Abstract_State:: 309* Aspect Annotate:: 310* Aspect Async_Readers:: 311* Aspect Async_Writers:: 312* Aspect Constant_After_Elaboration:: 313* Aspect Contract_Cases:: 314* Aspect Depends:: 315* Aspect Default_Initial_Condition:: 316* Aspect Dimension:: 317* Aspect Dimension_System:: 318* Aspect Disable_Controlled:: 319* Aspect Effective_Reads:: 320* Aspect Effective_Writes:: 321* Aspect Extensions_Visible:: 322* Aspect Favor_Top_Level:: 323* Aspect Ghost:: 324* Aspect Global:: 325* Aspect Initial_Condition:: 326* Aspect Initializes:: 327* Aspect Inline_Always:: 328* Aspect Invariant:: 329* Aspect Invariant'Class:: 330* Aspect Iterable:: 331* Aspect Linker_Section:: 332* Aspect Lock_Free:: 333* Aspect Max_Queue_Length:: 334* Aspect No_Elaboration_Code_All:: 335* Aspect No_Inline:: 336* Aspect No_Tagged_Streams:: 337* Aspect Object_Size:: 338* Aspect Obsolescent:: 339* Aspect Part_Of:: 340* Aspect Persistent_BSS:: 341* Aspect Predicate:: 342* Aspect Pure_Function:: 343* Aspect Refined_Depends:: 344* Aspect Refined_Global:: 345* Aspect Refined_Post:: 346* Aspect Refined_State:: 347* Aspect Remote_Access_Type:: 348* Aspect Secondary_Stack_Size:: 349* Aspect Scalar_Storage_Order:: 350* Aspect Shared:: 351* Aspect Simple_Storage_Pool:: 352* Aspect Simple_Storage_Pool_Type:: 353* Aspect SPARK_Mode:: 354* Aspect Suppress_Debug_Info:: 355* Aspect Suppress_Initialization:: 356* Aspect Test_Case:: 357* Aspect Thread_Local_Storage:: 358* Aspect Universal_Aliasing:: 359* Aspect Universal_Data:: 360* Aspect Unmodified:: 361* Aspect Unreferenced:: 362* Aspect Unreferenced_Objects:: 363* Aspect Value_Size:: 364* Aspect Volatile_Full_Access:: 365* Aspect Volatile_Function:: 366* Aspect Warnings:: 367 368Implementation Defined Attributes 369 370* Attribute Abort_Signal:: 371* Attribute Address_Size:: 372* Attribute Asm_Input:: 373* Attribute Asm_Output:: 374* Attribute Atomic_Always_Lock_Free:: 375* Attribute Bit:: 376* Attribute Bit_Position:: 377* Attribute Code_Address:: 378* Attribute Compiler_Version:: 379* Attribute Constrained:: 380* Attribute Default_Bit_Order:: 381* Attribute Default_Scalar_Storage_Order:: 382* Attribute Deref:: 383* Attribute Descriptor_Size:: 384* Attribute Elaborated:: 385* Attribute Elab_Body:: 386* Attribute Elab_Spec:: 387* Attribute Elab_Subp_Body:: 388* Attribute Emax:: 389* Attribute Enabled:: 390* Attribute Enum_Rep:: 391* Attribute Enum_Val:: 392* Attribute Epsilon:: 393* Attribute Fast_Math:: 394* Attribute Finalization_Size:: 395* Attribute Fixed_Value:: 396* Attribute From_Any:: 397* Attribute Has_Access_Values:: 398* Attribute Has_Discriminants:: 399* Attribute Img:: 400* Attribute Integer_Value:: 401* Attribute Invalid_Value:: 402* Attribute Iterable:: 403* Attribute Large:: 404* Attribute Library_Level:: 405* Attribute Lock_Free:: 406* Attribute Loop_Entry:: 407* Attribute Machine_Size:: 408* Attribute Mantissa:: 409* Attribute Maximum_Alignment:: 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 Storage_Unit:: 426* Attribute Stub_Type:: 427* Attribute System_Allocator_Alignment:: 428* Attribute Target_Name:: 429* Attribute To_Address:: 430* Attribute To_Any:: 431* Attribute Type_Class:: 432* Attribute Type_Key:: 433* Attribute TypeCode:: 434* Attribute Unconstrained_Array:: 435* Attribute Universal_Literal_String:: 436* Attribute Unrestricted_Access:: 437* Attribute Update:: 438* Attribute Valid_Scalars:: 439* Attribute VADS_Size:: 440* Attribute Value_Size:: 441* Attribute Wchar_T_Size:: 442* Attribute Word_Size:: 443 444Standard and Implementation Defined Restrictions 445 446* Partition-Wide Restrictions:: 447* Program Unit Level Restrictions:: 448 449Partition-Wide Restrictions 450 451* Immediate_Reclamation:: 452* Max_Asynchronous_Select_Nesting:: 453* Max_Entry_Queue_Length:: 454* Max_Protected_Entries:: 455* Max_Select_Alternatives:: 456* Max_Storage_At_Blocking:: 457* Max_Task_Entries:: 458* Max_Tasks:: 459* No_Abort_Statements:: 460* No_Access_Parameter_Allocators:: 461* No_Access_Subprograms:: 462* No_Allocators:: 463* No_Anonymous_Allocators:: 464* No_Asynchronous_Control:: 465* No_Calendar:: 466* No_Coextensions:: 467* No_Default_Initialization:: 468* No_Delay:: 469* No_Dependence:: 470* No_Direct_Boolean_Operators:: 471* No_Dispatch:: 472* No_Dispatching_Calls:: 473* No_Dynamic_Attachment:: 474* No_Dynamic_Priorities:: 475* No_Entry_Calls_In_Elaboration_Code:: 476* No_Enumeration_Maps:: 477* No_Exception_Handlers:: 478* No_Exception_Propagation:: 479* No_Exception_Registration:: 480* No_Exceptions:: 481* No_Finalization:: 482* No_Fixed_Point:: 483* No_Floating_Point:: 484* No_Implicit_Conditionals:: 485* No_Implicit_Dynamic_Code:: 486* No_Implicit_Heap_Allocations:: 487* No_Implicit_Protected_Object_Allocations:: 488* No_Implicit_Task_Allocations:: 489* No_Initialize_Scalars:: 490* No_IO:: 491* No_Local_Allocators:: 492* No_Local_Protected_Objects:: 493* No_Local_Timing_Events:: 494* No_Long_Long_Integers:: 495* No_Multiple_Elaboration:: 496* No_Nested_Finalization:: 497* No_Protected_Type_Allocators:: 498* No_Protected_Types:: 499* No_Recursion:: 500* No_Reentrancy:: 501* No_Relative_Delay:: 502* No_Requeue_Statements:: 503* No_Secondary_Stack:: 504* No_Select_Statements:: 505* No_Specific_Termination_Handlers:: 506* No_Specification_of_Aspect:: 507* No_Standard_Allocators_After_Elaboration:: 508* No_Standard_Storage_Pools:: 509* No_Stream_Optimizations:: 510* No_Streams:: 511* No_Task_Allocators:: 512* No_Task_At_Interrupt_Priority:: 513* No_Task_Attributes_Package:: 514* No_Task_Hierarchy:: 515* No_Task_Termination:: 516* No_Tasking:: 517* No_Terminate_Alternatives:: 518* No_Unchecked_Access:: 519* No_Unchecked_Conversion:: 520* No_Unchecked_Deallocation:: 521* No_Use_Of_Entity:: 522* Pure_Barriers:: 523* Simple_Barriers:: 524* Static_Priorities:: 525* Static_Storage_Size:: 526 527Program Unit Level Restrictions 528 529* No_Elaboration_Code:: 530* No_Dynamic_Sized_Objects:: 531* No_Entry_Queue:: 532* No_Implementation_Aspect_Specifications:: 533* No_Implementation_Attributes:: 534* No_Implementation_Identifiers:: 535* No_Implementation_Pragmas:: 536* No_Implementation_Restrictions:: 537* No_Implementation_Units:: 538* No_Implicit_Aliasing:: 539* No_Implicit_Loops:: 540* No_Obsolescent_Features:: 541* No_Wide_Characters:: 542* Static_Dispatch_Tables:: 543* SPARK_05:: 544 545Implementation Advice 546 547* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 548* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 549* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 550* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 551* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 552* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 553* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 554* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 555* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 556* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 557* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 558* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 559* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 560* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 561* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 562* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 563* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 564* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 565* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 566* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 567* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 568* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 569* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 570* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 571* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 572* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 573* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 574* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 575* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 576* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 577* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 578* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 579* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 580* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 581* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 582* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 583* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 584* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 585* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 586* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 587* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 588* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 589* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 590* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 591* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 592* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 593* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 594* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 595* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 596* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 597* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 598* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 599* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 600* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 601* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 602* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 603* RM F(7); COBOL Support: RM F 7 COBOL Support. 604* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 605* RM G; Numerics: RM G Numerics. 606* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 607* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 608* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 609* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 610* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 611 612Intrinsic Subprograms 613 614* Intrinsic Operators:: 615* Compilation_ISO_Date:: 616* Compilation_Date:: 617* Compilation_Time:: 618* Enclosing_Entity:: 619* Exception_Information:: 620* Exception_Message:: 621* Exception_Name:: 622* File:: 623* Line:: 624* Shifts and Rotates:: 625* Source_Location:: 626 627Representation Clauses and Pragmas 628 629* Alignment Clauses:: 630* Size Clauses:: 631* Storage_Size Clauses:: 632* Size of Variant Record Objects:: 633* Biased Representation:: 634* Value_Size and Object_Size Clauses:: 635* Component_Size Clauses:: 636* Bit_Order Clauses:: 637* Effect of Bit_Order on Byte Ordering:: 638* Pragma Pack for Arrays:: 639* Pragma Pack for Records:: 640* Record Representation Clauses:: 641* Handling of Records with Holes:: 642* Enumeration Clauses:: 643* Address Clauses:: 644* Use of Address Clauses for Memory-Mapped I/O:: 645* Effect of Convention on Representation:: 646* Conventions and Anonymous Access Types:: 647* Determining the Representations chosen by GNAT:: 648 649The Implementation of Standard I/O 650 651* Standard I/O Packages:: 652* FORM Strings:: 653* Direct_IO:: 654* Sequential_IO:: 655* Text_IO:: 656* Wide_Text_IO:: 657* Wide_Wide_Text_IO:: 658* Stream_IO:: 659* Text Translation:: 660* Shared Files:: 661* Filenames encoding:: 662* File content encoding:: 663* Open Modes:: 664* Operations on C Streams:: 665* Interfacing to C Streams:: 666 667Text_IO 668 669* Stream Pointer Positioning:: 670* Reading and Writing Non-Regular Files:: 671* Get_Immediate:: 672* Treating Text_IO Files as Streams:: 673* Text_IO Extensions:: 674* Text_IO Facilities for Unbounded Strings:: 675 676Wide_Text_IO 677 678* Stream Pointer Positioning: Stream Pointer Positioning<2>. 679* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 680 681Wide_Wide_Text_IO 682 683* Stream Pointer Positioning: Stream Pointer Positioning<3>. 684* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 685 686The GNAT Library 687 688* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 689* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 690* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 691* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 692* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 693* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 694* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 695* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 696* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 697* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 698* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 699* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 700* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 701* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 702* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 703* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 704* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 705* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 706* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 707* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 708* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 709* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 710* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 711* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 712* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 713* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 714* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 715* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 716* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 717* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 718* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 719* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 720* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 721* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 722* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 723* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 724* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 725* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 726* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 727* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 728* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 729* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 730* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 731* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 732* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 733* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 734* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 735* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 736* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 737* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 738* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 739* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 740* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 741* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 742* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 743* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 744* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 745* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 746* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 747* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 748* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 749* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 750* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 751* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 752* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 753* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 754* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 755* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 756* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 757* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 758* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 759* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 760* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 761* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 762* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 763* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 764* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 765* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 766* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 767* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 768* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 769* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 770* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 771* GNAT.IO (g-io.ads): GNAT IO g-io ads. 772* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 773* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 774* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 775* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 776* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 777* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 778* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 779* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 780* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 781* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 782* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 783* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 784* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 785* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 786* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 787* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 788* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 789* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 790* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 791* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 792* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 793* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 794* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 795* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 796* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 797* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 798* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 799* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 800* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 801* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 802* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 803* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 804* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 805* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 806* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 807* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 808* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 809* GNAT.Table (g-table.ads): GNAT Table g-table ads. 810* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 811* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 812* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 813* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 814* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 815* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 816* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 817* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 818* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 819* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 820* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 821* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 822* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 823* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 824* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 825* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 826* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 827* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 828* System.Assertions (s-assert.ads): System Assertions s-assert ads. 829* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 830* System.Memory (s-memory.ads): System Memory s-memory ads. 831* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 832* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 833* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 834* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 835* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 836* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 837* System.Rident (s-rident.ads): System Rident s-rident ads. 838* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 839* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 840* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 841* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 842 843Interfacing to Other Languages 844 845* Interfacing to C:: 846* Interfacing to C++:: 847* Interfacing to COBOL:: 848* Interfacing to Fortran:: 849* Interfacing to non-GNAT Ada code:: 850 851Implementation of Specific Ada Features 852 853* Machine Code Insertions:: 854* GNAT Implementation of Tasking:: 855* GNAT Implementation of Shared Passive Packages:: 856* Code Generation for Array Aggregates:: 857* The Size of Discriminated Records with Default Discriminants:: 858* Strict Conformance to the Ada Reference Manual:: 859 860GNAT Implementation of Tasking 861 862* Mapping Ada Tasks onto the Underlying Kernel Threads:: 863* Ensuring Compliance with the Real-Time Annex:: 864* Support for Locking Policies:: 865 866Code Generation for Array Aggregates 867 868* Static constant aggregates with static bounds:: 869* Constant aggregates with unconstrained nominal types:: 870* Aggregates with static bounds:: 871* Aggregates with nonstatic bounds:: 872* Aggregates in assignment statements:: 873 874Obsolescent Features 875 876* pragma No_Run_Time:: 877* pragma Ravenscar:: 878* pragma Restricted_Run_Time:: 879* pragma Task_Info:: 880* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 881 882Compatibility and Porting Guide 883 884* Writing Portable Fixed-Point Declarations:: 885* Compatibility with Ada 83:: 886* Compatibility between Ada 95 and Ada 2005:: 887* Implementation-dependent characteristics:: 888* Compatibility with Other Ada Systems:: 889* Representation Clauses:: 890* Compatibility with HP Ada 83:: 891 892Compatibility with Ada 83 893 894* Legal Ada 83 programs that are illegal in Ada 95:: 895* More deterministic semantics:: 896* Changed semantics:: 897* Other language compatibility issues:: 898 899Implementation-dependent characteristics 900 901* Implementation-defined pragmas:: 902* Implementation-defined attributes:: 903* Libraries:: 904* Elaboration order:: 905* Target-specific aspects:: 906 907@end detailmenu 908@end menu 909 910@node About This Guide,Implementation Defined Pragmas,Top,Top 911@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{2}@anchor{gnat_rm/about_this_guide doc}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5} 912@chapter About This Guide 913 914 915 916This manual contains useful information in writing programs using the 917GNAT compiler. It includes information on implementation dependent 918characteristics of GNAT, including all the information required by 919Annex M of the Ada language standard. 920 921GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 922invoked in Ada 83 compatibility mode. 923By default, GNAT assumes Ada 2012, 924but you can override with a compiler switch 925to explicitly specify the language version. 926(Please refer to the @emph{GNAT User's Guide} for details on these switches.) 927Throughout this manual, references to 'Ada' without a year suffix 928apply to all the Ada versions of the language. 929 930Ada is designed to be highly portable. 931In general, a program will have the same effect even when compiled by 932different compilers on different platforms. 933However, since Ada is designed to be used in a 934wide variety of applications, it also contains a number of system 935dependent features to be used in interfacing to the external world. 936 937@geindex Implementation-dependent features 938 939@geindex Portability 940 941Note: Any program that makes use of implementation-dependent features 942may be non-portable. You should follow good programming practice and 943isolate and clearly document any sections of your program that make use 944of these features in a non-portable manner. 945 946@menu 947* What This Reference Manual Contains:: 948* Conventions:: 949* Related Information:: 950 951@end menu 952 953@node What This Reference Manual Contains,Conventions,,About This Guide 954@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 955@section What This Reference Manual Contains 956 957 958This reference manual contains the following chapters: 959 960 961@itemize * 962 963@item 964@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 965pragmas, which can be used to extend and enhance the functionality of the 966compiler. 967 968@item 969@ref{8,,Implementation Defined Attributes}, lists GNAT 970implementation-dependent attributes, which can be used to extend and 971enhance the functionality of the compiler. 972 973@item 974@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 975implementation-dependent restrictions, which can be used to extend and 976enhance the functionality of the compiler. 977 978@item 979@ref{a,,Implementation Advice}, provides information on generally 980desirable behavior which are not requirements that all compilers must 981follow since it cannot be provided on all systems, or which may be 982undesirable on some systems. 983 984@item 985@ref{b,,Implementation Defined Characteristics}, provides a guide to 986minimizing implementation dependent features. 987 988@item 989@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 990implemented by GNAT, and how they can be imported into user 991application programs. 992 993@item 994@ref{d,,Representation Clauses and Pragmas}, describes in detail the 995way that GNAT represents data, and in particular the exact set 996of representation clauses and pragmas that is accepted. 997 998@item 999@ref{e,,Standard Library Routines}, provides a listing of packages and a 1000brief description of the functionality that is provided by Ada's 1001extensive set of standard library routines as implemented by GNAT. 1002 1003@item 1004@ref{f,,The Implementation of Standard I/O}, details how the GNAT 1005implementation of the input-output facilities. 1006 1007@item 1008@ref{10,,The GNAT Library}, is a catalog of packages that complement 1009the Ada predefined library. 1010 1011@item 1012@ref{11,,Interfacing to Other Languages}, describes how programs 1013written in Ada using GNAT can be interfaced to other programming 1014languages. 1015 1016@item 1017@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 1018of the specialized needs annexes. 1019 1020@item 1021@ref{13,,Implementation of Specific Ada Features}, discusses issues related 1022to GNAT's implementation of machine code insertions, tasking, and several 1023other features. 1024 1025@item 1026@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1027GNAT implementation of the Ada 2012 language standard. 1028 1029@item 1030@ref{15,,Obsolescent Features} documents implementation dependent features, 1031including pragmas and attributes, which are considered obsolescent, since 1032there are other preferred ways of achieving the same results. These 1033obsolescent forms are retained for backwards compatibility. 1034 1035@item 1036@ref{16,,Compatibility and Porting Guide} presents some guidelines for 1037developing portable Ada code, describes the compatibility issues that 1038may arise between GNAT and other Ada compilation systems (including those 1039for Ada 83), and shows how GNAT can expedite porting applications 1040developed in other Ada environments. 1041 1042@item 1043@ref{1,,GNU Free Documentation License} contains the license for this document. 1044@end itemize 1045 1046@geindex Ada 95 Language Reference Manual 1047 1048@geindex Ada 2005 Language Reference Manual 1049 1050This reference manual assumes a basic familiarity with the Ada 95 language, as 1051described in the 1052@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1053It does not require knowledge of the new features introduced by Ada 2005 or 1054Ada 2012. 1055All three reference manuals are included in the GNAT documentation 1056package. 1057 1058@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1059@anchor{gnat_rm/about_this_guide conventions}@anchor{17} 1060@section Conventions 1061 1062 1063@geindex Conventions 1064@geindex typographical 1065 1066@geindex Typographical conventions 1067 1068Following are examples of the typographical and graphic conventions used 1069in this guide: 1070 1071 1072@itemize * 1073 1074@item 1075@code{Functions}, @code{utility program names}, @code{standard names}, 1076and @code{classes}. 1077 1078@item 1079@code{Option flags} 1080 1081@item 1082@code{File names} 1083 1084@item 1085@code{Variables} 1086 1087@item 1088@emph{Emphasis} 1089 1090@item 1091[optional information or parameters] 1092 1093@item 1094Examples are described by text 1095 1096@example 1097and then shown this way. 1098@end example 1099 1100@item 1101Commands that are entered by the user are shown as preceded by a prompt string 1102comprising the @code{$} character followed by a space. 1103@end itemize 1104 1105@node Related Information,,Conventions,About This Guide 1106@anchor{gnat_rm/about_this_guide related-information}@anchor{18} 1107@section Related Information 1108 1109 1110See the following documents for further information on GNAT: 1111 1112 1113@itemize * 1114 1115@item 1116@cite{GNAT User's Guide for Native Platforms}, 1117which provides information on how to use the 1118GNAT development environment. 1119 1120@item 1121@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1122 1123@item 1124@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1125of the Ada 95 standard. The annotations describe 1126detailed aspects of the design decision, and in particular contain useful 1127sections on Ada 83 compatibility. 1128 1129@item 1130@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1131 1132@item 1133@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1134of the Ada 2005 standard. The annotations describe 1135detailed aspects of the design decision. 1136 1137@item 1138@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1139 1140@item 1141@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1142which contains specific information on compatibility between GNAT and 1143DEC Ada 83 systems. 1144 1145@item 1146@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1147describes in detail the pragmas and attributes provided by the DEC Ada 83 1148compiler system. 1149@end itemize 1150 1151@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1152@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7}@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{19}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1a} 1153@chapter Implementation Defined Pragmas 1154 1155 1156Ada defines a set of pragmas that can be used to supply additional 1157information to the compiler. These language defined pragmas are 1158implemented in GNAT and work as described in the Ada Reference Manual. 1159 1160In addition, Ada allows implementations to define additional pragmas 1161whose meaning is defined by the implementation. GNAT provides a number 1162of these implementation-defined pragmas, which can be used to extend 1163and enhance the functionality of the compiler. This section of the GNAT 1164Reference Manual describes these additional pragmas. 1165 1166Note that any program using these pragmas might not be portable to other 1167compilers (although GNAT implements this set of pragmas on all 1168platforms). Therefore if portability to other compilers is an important 1169consideration, the use of these pragmas should be minimized. 1170 1171@menu 1172* Pragma Abort_Defer:: 1173* Pragma Abstract_State:: 1174* Pragma Acc_Parallel:: 1175* Pragma Acc_Loop:: 1176* Pragma Acc_Kernels:: 1177* Pragma Acc_Data:: 1178* Pragma Ada_83:: 1179* Pragma Ada_95:: 1180* Pragma Ada_05:: 1181* Pragma Ada_2005:: 1182* Pragma Ada_12:: 1183* Pragma Ada_2012:: 1184* Pragma Allow_Integer_Address:: 1185* Pragma Annotate:: 1186* Pragma Assert:: 1187* Pragma Assert_And_Cut:: 1188* Pragma Assertion_Policy:: 1189* Pragma Assume:: 1190* Pragma Assume_No_Invalid_Values:: 1191* Pragma Async_Readers:: 1192* Pragma Async_Writers:: 1193* Pragma Attribute_Definition:: 1194* Pragma C_Pass_By_Copy:: 1195* Pragma Check:: 1196* Pragma Check_Float_Overflow:: 1197* Pragma Check_Name:: 1198* Pragma Check_Policy:: 1199* Pragma Comment:: 1200* Pragma Common_Object:: 1201* Pragma Compile_Time_Error:: 1202* Pragma Compile_Time_Warning:: 1203* Pragma Compiler_Unit:: 1204* Pragma Compiler_Unit_Warning:: 1205* Pragma Complete_Representation:: 1206* Pragma Complex_Representation:: 1207* Pragma Component_Alignment:: 1208* Pragma Constant_After_Elaboration:: 1209* Pragma Contract_Cases:: 1210* Pragma Convention_Identifier:: 1211* Pragma CPP_Class:: 1212* Pragma CPP_Constructor:: 1213* Pragma CPP_Virtual:: 1214* Pragma CPP_Vtable:: 1215* Pragma CPU:: 1216* Pragma Deadline_Floor:: 1217* Pragma Default_Initial_Condition:: 1218* Pragma Debug:: 1219* Pragma Debug_Policy:: 1220* Pragma Default_Scalar_Storage_Order:: 1221* Pragma Default_Storage_Pool:: 1222* Pragma Depends:: 1223* Pragma Detect_Blocking:: 1224* Pragma Disable_Atomic_Synchronization:: 1225* Pragma Dispatching_Domain:: 1226* Pragma Effective_Reads:: 1227* Pragma Effective_Writes:: 1228* Pragma Elaboration_Checks:: 1229* Pragma Eliminate:: 1230* Pragma Enable_Atomic_Synchronization:: 1231* Pragma Export_Function:: 1232* Pragma Export_Object:: 1233* Pragma Export_Procedure:: 1234* Pragma Export_Value:: 1235* Pragma Export_Valued_Procedure:: 1236* Pragma Extend_System:: 1237* Pragma Extensions_Allowed:: 1238* Pragma Extensions_Visible:: 1239* Pragma External:: 1240* Pragma External_Name_Casing:: 1241* Pragma Fast_Math:: 1242* Pragma Favor_Top_Level:: 1243* Pragma Finalize_Storage_Only:: 1244* Pragma Float_Representation:: 1245* Pragma Ghost:: 1246* Pragma Global:: 1247* Pragma Ident:: 1248* Pragma Ignore_Pragma:: 1249* Pragma Implementation_Defined:: 1250* Pragma Implemented:: 1251* Pragma Implicit_Packing:: 1252* Pragma Import_Function:: 1253* Pragma Import_Object:: 1254* Pragma Import_Procedure:: 1255* Pragma Import_Valued_Procedure:: 1256* Pragma Independent:: 1257* Pragma Independent_Components:: 1258* Pragma Initial_Condition:: 1259* Pragma Initialize_Scalars:: 1260* Pragma Initializes:: 1261* Pragma Inline_Always:: 1262* Pragma Inline_Generic:: 1263* Pragma Interface:: 1264* Pragma Interface_Name:: 1265* Pragma Interrupt_Handler:: 1266* Pragma Interrupt_State:: 1267* Pragma Invariant:: 1268* Pragma Keep_Names:: 1269* Pragma License:: 1270* Pragma Link_With:: 1271* Pragma Linker_Alias:: 1272* Pragma Linker_Constructor:: 1273* Pragma Linker_Destructor:: 1274* Pragma Linker_Section:: 1275* Pragma Lock_Free:: 1276* Pragma Loop_Invariant:: 1277* Pragma Loop_Optimize:: 1278* Pragma Loop_Variant:: 1279* Pragma Machine_Attribute:: 1280* Pragma Main:: 1281* Pragma Main_Storage:: 1282* Pragma Max_Queue_Length:: 1283* Pragma No_Body:: 1284* Pragma No_Component_Reordering:: 1285* Pragma No_Elaboration_Code_All:: 1286* Pragma No_Heap_Finalization:: 1287* Pragma No_Inline:: 1288* Pragma No_Return:: 1289* Pragma No_Run_Time:: 1290* Pragma No_Strict_Aliasing:: 1291* Pragma No_Tagged_Streams:: 1292* Pragma Normalize_Scalars:: 1293* Pragma Obsolescent:: 1294* Pragma Optimize_Alignment:: 1295* Pragma Ordered:: 1296* Pragma Overflow_Mode:: 1297* Pragma Overriding_Renamings:: 1298* Pragma Partition_Elaboration_Policy:: 1299* Pragma Part_Of:: 1300* Pragma Passive:: 1301* Pragma Persistent_BSS:: 1302* Pragma Polling:: 1303* Pragma Post:: 1304* Pragma Postcondition:: 1305* Pragma Post_Class:: 1306* Pragma Rename_Pragma:: 1307* Pragma Pre:: 1308* Pragma Precondition:: 1309* Pragma Predicate:: 1310* Pragma Predicate_Failure:: 1311* Pragma Preelaborable_Initialization:: 1312* Pragma Prefix_Exception_Messages:: 1313* Pragma Pre_Class:: 1314* Pragma Priority_Specific_Dispatching:: 1315* Pragma Profile:: 1316* Pragma Profile_Warnings:: 1317* Pragma Propagate_Exceptions:: 1318* Pragma Provide_Shift_Operators:: 1319* Pragma Psect_Object:: 1320* Pragma Pure_Function:: 1321* Pragma Rational:: 1322* Pragma Ravenscar:: 1323* Pragma Refined_Depends:: 1324* Pragma Refined_Global:: 1325* Pragma Refined_Post:: 1326* Pragma Refined_State:: 1327* Pragma Relative_Deadline:: 1328* Pragma Remote_Access_Type:: 1329* Pragma Restricted_Run_Time:: 1330* Pragma Restriction_Warnings:: 1331* Pragma Reviewable:: 1332* Pragma Secondary_Stack_Size:: 1333* Pragma Share_Generic:: 1334* Pragma Shared:: 1335* Pragma Short_Circuit_And_Or:: 1336* Pragma Short_Descriptors:: 1337* Pragma Simple_Storage_Pool_Type:: 1338* Pragma Source_File_Name:: 1339* Pragma Source_File_Name_Project:: 1340* Pragma Source_Reference:: 1341* Pragma SPARK_Mode:: 1342* Pragma Static_Elaboration_Desired:: 1343* Pragma Stream_Convert:: 1344* Pragma Style_Checks:: 1345* Pragma Subtitle:: 1346* Pragma Suppress:: 1347* Pragma Suppress_All:: 1348* Pragma Suppress_Debug_Info:: 1349* Pragma Suppress_Exception_Locations:: 1350* Pragma Suppress_Initialization:: 1351* Pragma Task_Name:: 1352* Pragma Task_Storage:: 1353* Pragma Test_Case:: 1354* Pragma Thread_Local_Storage:: 1355* Pragma Time_Slice:: 1356* Pragma Title:: 1357* Pragma Type_Invariant:: 1358* Pragma Type_Invariant_Class:: 1359* Pragma Unchecked_Union:: 1360* Pragma Unevaluated_Use_Of_Old:: 1361* Pragma Unimplemented_Unit:: 1362* Pragma Universal_Aliasing:: 1363* Pragma Universal_Data:: 1364* Pragma Unmodified:: 1365* Pragma Unreferenced:: 1366* Pragma Unreferenced_Objects:: 1367* Pragma Unreserve_All_Interrupts:: 1368* Pragma Unsuppress:: 1369* Pragma Use_VADS_Size:: 1370* Pragma Unused:: 1371* Pragma Validity_Checks:: 1372* Pragma Volatile:: 1373* Pragma Volatile_Full_Access:: 1374* Pragma Volatile_Function:: 1375* Pragma Warning_As_Error:: 1376* Pragma Warnings:: 1377* Pragma Weak_External:: 1378* Pragma Wide_Character_Encoding:: 1379 1380@end menu 1381 1382@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1383@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b} 1384@section Pragma Abort_Defer 1385 1386 1387@geindex Deferring aborts 1388 1389Syntax: 1390 1391@example 1392pragma Abort_Defer; 1393@end example 1394 1395This pragma must appear at the start of the statement sequence of a 1396handled sequence of statements (right after the @code{begin}). It has 1397the effect of deferring aborts for the sequence of statements (but not 1398for the declarations or handlers, if any, associated with this statement 1399sequence). 1400 1401@node Pragma Abstract_State,Pragma Acc_Parallel,Pragma Abort_Defer,Implementation Defined Pragmas 1402@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d} 1403@section Pragma Abstract_State 1404 1405 1406Syntax: 1407 1408@example 1409pragma Abstract_State (ABSTRACT_STATE_LIST); 1410 1411ABSTRACT_STATE_LIST ::= 1412 null 1413 | STATE_NAME_WITH_OPTIONS 1414 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1415 1416STATE_NAME_WITH_OPTIONS ::= 1417 STATE_NAME 1418 | (STATE_NAME with OPTION_LIST) 1419 1420OPTION_LIST ::= OPTION @{, OPTION@} 1421 1422OPTION ::= 1423 SIMPLE_OPTION 1424 | NAME_VALUE_OPTION 1425 1426SIMPLE_OPTION ::= Ghost | Synchronous 1427 1428NAME_VALUE_OPTION ::= 1429 Part_Of => ABSTRACT_STATE 1430 | External [=> EXTERNAL_PROPERTY_LIST] 1431 1432EXTERNAL_PROPERTY_LIST ::= 1433 EXTERNAL_PROPERTY 1434 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1435 1436EXTERNAL_PROPERTY ::= 1437 Async_Readers [=> boolean_EXPRESSION] 1438 | Async_Writers [=> boolean_EXPRESSION] 1439 | Effective_Reads [=> boolean_EXPRESSION] 1440 | Effective_Writes [=> boolean_EXPRESSION] 1441 others => boolean_EXPRESSION 1442 1443STATE_NAME ::= defining_identifier 1444 1445ABSTRACT_STATE ::= name 1446@end example 1447 1448For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in 1449the SPARK 2014 Reference Manual, section 7.1.4. 1450 1451@node Pragma Acc_Parallel,Pragma Acc_Loop,Pragma Abstract_State,Implementation Defined Pragmas 1452@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-parallel}@anchor{1e} 1453@section Pragma Acc_Parallel 1454 1455 1456Syntax: 1457 1458@example 1459pragma Acc_Parallel [( ACC_PARALLEL_CLAUSE [, ACC_PARALLEL_CLAUSE... ])]; 1460 1461ACC_PARALLEL_CLAUSE ::= 1462 Acc_If => boolean_EXPRESSION 1463 | Acc_Private => IDENTIFIERS 1464 | Async => integer_EXPRESSION 1465 | Copy => IDENTIFIERS 1466 | Copy_In => IDENTIFIERS 1467 | Copy_Out => IDENTIFIERS 1468 | Create => IDENTIFIERS 1469 | Default => None 1470 | Device_Ptr => IDENTIFIERS 1471 | First_Private => IDENTIFIERS 1472 | Num_Gangs => integer_EXPRESSION 1473 | Num_Workers => integer_EXPRESSION 1474 | Present => IDENTIFIERS 1475 | Reduction => (REDUCTION_RECORD) 1476 | Vector_Length => integer_EXPRESSION 1477 | Wait => INTEGERS 1478 1479REDUCTION_RECORD ::= 1480 "+" => IDENTIFIERS 1481 | "*" => IDENTIFIERS 1482 | "min" => IDENTIFIERS 1483 | "max" => IDENTIFIERS 1484 | "or" => IDENTIFIERS 1485 | "and" => IDENTIFIERS 1486 1487IDENTIFIERS ::= 1488 | IDENTIFIER 1489 | (IDENTIFIER, IDENTIFIERS) 1490 1491INTEGERS ::= 1492 | integer_EXPRESSION 1493 | (integer_EXPRESSION, INTEGERS) 1494@end example 1495 1496Requires the @code{-fopenacc} flag. 1497 1498Equivalent to the @code{parallel} directive of the OpenAcc standard. This pragma 1499should be placed in loops. It offloads the content of the loop to an 1500accelerator device. 1501 1502For more information about the effect of the clauses, see the OpenAcc 1503specification. 1504 1505@node Pragma Acc_Loop,Pragma Acc_Kernels,Pragma Acc_Parallel,Implementation Defined Pragmas 1506@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-loop}@anchor{1f} 1507@section Pragma Acc_Loop 1508 1509 1510Syntax: 1511 1512@example 1513pragma Acc_Loop [( ACC_LOOP_CLAUSE [, ACC_LOOP_CLAUSE... ])]; 1514 1515ACC_LOOP_CLAUSE ::= 1516 Auto 1517 | Collapse => INTEGER_LITERAL 1518 | Gang [=> GANG_ARG] 1519 | Independent 1520 | Private => IDENTIFIERS 1521 | Reduction => (REDUCTION_RECORD) 1522 | Seq 1523 | Tile => SIZE_EXPRESSION 1524 | Vector [=> integer_EXPRESSION] 1525 | Worker [=> integer_EXPRESSION] 1526 1527GANG_ARG ::= 1528 integer_EXPRESSION 1529 | Static => SIZE_EXPRESSION 1530 1531SIZE_EXPRESSION ::= 1532 * 1533 | integer_EXPRESSION 1534@end example 1535 1536Requires the @code{-fopenacc} flag. 1537 1538Equivalent to the @code{loop} directive of the OpenAcc standard. This pragma 1539should be placed in for loops after the "Acc_Parallel" pragma. It tells the 1540compiler how to parallelize the loop. 1541 1542For more information about the effect of the clauses, see the OpenAcc 1543specification. 1544 1545@node Pragma Acc_Kernels,Pragma Acc_Data,Pragma Acc_Loop,Implementation Defined Pragmas 1546@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-kernels}@anchor{20} 1547@section Pragma Acc_Kernels 1548 1549 1550Syntax: 1551 1552@example 1553pragma Acc_Kernels [( ACC_KERNELS_CLAUSE [, ACC_KERNELS_CLAUSE...])]; 1554 1555ACC_KERNELS_CLAUSE ::= 1556 Acc_If => boolean_EXPRESSION 1557 | Async => integer_EXPRESSION 1558 | Copy => IDENTIFIERS 1559 | Copy_In => IDENTIFIERS 1560 | Copy_Out => IDENTIFIERS 1561 | Create => IDENTIFIERS 1562 | Default => None 1563 | Device_Ptr => IDENTIFIERS 1564 | Num_Gangs => integer_EXPRESSION 1565 | Num_Workers => integer_EXPRESSION 1566 | Present => IDENTIFIERS 1567 | Vector_Length => integer_EXPRESSION 1568 | Wait => INTEGERS 1569 1570IDENTIFIERS ::= 1571 | IDENTIFIER 1572 | (IDENTIFIER, IDENTIFIERS) 1573 1574INTEGERS ::= 1575 | integer_EXPRESSION 1576 | (integer_EXPRESSION, INTEGERS) 1577@end example 1578 1579Requires the @code{-fopenacc} flag. 1580 1581Equivalent to the kernels directive of the OpenAcc standard. This pragma should 1582be placed in loops. 1583 1584For more information about the effect of the clauses, see the OpenAcc 1585specification. 1586 1587@node Pragma Acc_Data,Pragma Ada_83,Pragma Acc_Kernels,Implementation Defined Pragmas 1588@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-data}@anchor{21} 1589@section Pragma Acc_Data 1590 1591 1592Syntax: 1593 1594@example 1595pragma Acc_Data ([ ACC_DATA_CLAUSE [, ACC_DATA_CLAUSE...]]); 1596 1597ACC_DATA_CLAUSE ::= 1598 Copy => IDENTIFIERS 1599 | Copy_In => IDENTIFIERS 1600 | Copy_Out => IDENTIFIERS 1601 | Create => IDENTIFIERS 1602 | Device_Ptr => IDENTIFIERS 1603 | Present => IDENTIFIERS 1604@end example 1605 1606Requires the @code{-fopenacc} flag. 1607 1608Equivalent to the @code{data} directive of the OpenAcc standard. This pragma 1609should be placed in loops. 1610 1611For more information about the effect of the clauses, see the OpenAcc 1612specification. 1613 1614@node Pragma Ada_83,Pragma Ada_95,Pragma Acc_Data,Implementation Defined Pragmas 1615@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{22} 1616@section Pragma Ada_83 1617 1618 1619Syntax: 1620 1621@example 1622pragma Ada_83; 1623@end example 1624 1625A configuration pragma that establishes Ada 83 mode for the unit to 1626which it applies, regardless of the mode set by the command line 1627switches. In Ada 83 mode, GNAT attempts to be as compatible with 1628the syntax and semantics of Ada 83, as defined in the original Ada 162983 Reference Manual as possible. In particular, the keywords added by Ada 95 1630and Ada 2005 are not recognized, optional package bodies are allowed, 1631and generics may name types with unknown discriminants without using 1632the @code{(<>)} notation. In addition, some but not all of the additional 1633restrictions of Ada 83 are enforced. 1634 1635Ada 83 mode is intended for two purposes. Firstly, it allows existing 1636Ada 83 code to be compiled and adapted to GNAT with less effort. 1637Secondly, it aids in keeping code backwards compatible with Ada 83. 1638However, there is no guarantee that code that is processed correctly 1639by GNAT in Ada 83 mode will in fact compile and execute with an Ada 164083 compiler, since GNAT does not enforce all the additional checks 1641required by Ada 83. 1642 1643@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1644@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{23} 1645@section Pragma Ada_95 1646 1647 1648Syntax: 1649 1650@example 1651pragma Ada_95; 1652@end example 1653 1654A configuration pragma that establishes Ada 95 mode for the unit to which 1655it applies, regardless of the mode set by the command line switches. 1656This mode is set automatically for the @code{Ada} and @code{System} 1657packages and their children, so you need not specify it in these 1658contexts. This pragma is useful when writing a reusable component that 1659itself uses Ada 95 features, but which is intended to be usable from 1660either Ada 83 or Ada 95 programs. 1661 1662@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1663@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{24} 1664@section Pragma Ada_05 1665 1666 1667Syntax: 1668 1669@example 1670pragma Ada_05; 1671pragma Ada_05 (local_NAME); 1672@end example 1673 1674A configuration pragma that establishes Ada 2005 mode for the unit to which 1675it applies, regardless of the mode set by the command line switches. 1676This pragma is useful when writing a reusable component that 1677itself uses Ada 2005 features, but which is intended to be usable from 1678either Ada 83 or Ada 95 programs. 1679 1680The one argument form (which is not a configuration pragma) 1681is used for managing the transition from 1682Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1683as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1684mode will generate a warning. In addition, in Ada_83 or Ada_95 1685mode, a preference rule is established which does not choose 1686such an entity unless it is unambiguously specified. This avoids 1687extra subprograms marked this way from generating ambiguities in 1688otherwise legal pre-Ada_2005 programs. The one argument form is 1689intended for exclusive use in the GNAT run-time library. 1690 1691@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1692@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{25} 1693@section Pragma Ada_2005 1694 1695 1696Syntax: 1697 1698@example 1699pragma Ada_2005; 1700@end example 1701 1702This configuration pragma is a synonym for pragma Ada_05 and has the 1703same syntax and effect. 1704 1705@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1706@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{26} 1707@section Pragma Ada_12 1708 1709 1710Syntax: 1711 1712@example 1713pragma Ada_12; 1714pragma Ada_12 (local_NAME); 1715@end example 1716 1717A configuration pragma that establishes Ada 2012 mode for the unit to which 1718it applies, regardless of the mode set by the command line switches. 1719This mode is set automatically for the @code{Ada} and @code{System} 1720packages and their children, so you need not specify it in these 1721contexts. This pragma is useful when writing a reusable component that 1722itself uses Ada 2012 features, but which is intended to be usable from 1723Ada 83, Ada 95, or Ada 2005 programs. 1724 1725The one argument form, which is not a configuration pragma, 1726is used for managing the transition from Ada 17272005 to Ada 2012 in the run-time library. If an entity is marked 1728as Ada_2012 only, then referencing the entity in any pre-Ada_2012 1729mode will generate a warning. In addition, in any pre-Ada_2012 1730mode, a preference rule is established which does not choose 1731such an entity unless it is unambiguously specified. This avoids 1732extra subprograms marked this way from generating ambiguities in 1733otherwise legal pre-Ada_2012 programs. The one argument form is 1734intended for exclusive use in the GNAT run-time library. 1735 1736@node Pragma Ada_2012,Pragma Allow_Integer_Address,Pragma Ada_12,Implementation Defined Pragmas 1737@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{27} 1738@section Pragma Ada_2012 1739 1740 1741Syntax: 1742 1743@example 1744pragma Ada_2012; 1745@end example 1746 1747This configuration pragma is a synonym for pragma Ada_12 and has the 1748same syntax and effect. 1749 1750@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Ada_2012,Implementation Defined Pragmas 1751@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{28} 1752@section Pragma Allow_Integer_Address 1753 1754 1755Syntax: 1756 1757@example 1758pragma Allow_Integer_Address; 1759@end example 1760 1761In almost all versions of GNAT, @code{System.Address} is a private 1762type in accordance with the implementation advice in the RM. This 1763means that integer values, 1764in particular integer literals, are not allowed as address values. 1765If the configuration pragma 1766@code{Allow_Integer_Address} is given, then integer expressions may 1767be used anywhere a value of type @code{System.Address} is required. 1768The effect is to introduce an implicit unchecked conversion from the 1769integer value to type @code{System.Address}. The reverse case of using 1770an address where an integer type is required is handled analogously. 1771The following example compiles without errors: 1772 1773@example 1774pragma Allow_Integer_Address; 1775with System; use System; 1776package AddrAsInt is 1777 X : Integer; 1778 Y : Integer; 1779 for X'Address use 16#1240#; 1780 for Y use at 16#3230#; 1781 m : Address := 16#4000#; 1782 n : constant Address := 4000; 1783 p : constant Address := Address (X + Y); 1784 v : Integer := y'Address; 1785 w : constant Integer := Integer (Y'Address); 1786 type R is new integer; 1787 RR : R := 1000; 1788 Z : Integer; 1789 for Z'Address use RR; 1790end AddrAsInt; 1791@end example 1792 1793Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} 1794is not a private type. In implementations of @code{GNAT} where 1795System.Address is a visible integer type, 1796this pragma serves no purpose but is ignored 1797rather than rejected to allow common sets of sources to be used 1798in the two situations. 1799 1800@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1801@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{2a} 1802@section Pragma Annotate 1803 1804 1805Syntax: 1806 1807@example 1808pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1809 1810ARG ::= NAME | EXPRESSION 1811@end example 1812 1813This pragma is used to annotate programs. IDENTIFIER identifies 1814the type of annotation. GNAT verifies that it is an identifier, but does 1815not otherwise analyze it. The second optional identifier is also left 1816unanalyzed, and by convention is used to control the action of the tool to 1817which the annotation is addressed. The remaining ARG arguments 1818can be either string literals or more generally expressions. 1819String literals are assumed to be either of type 1820@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1821depending on the character literals they contain. 1822All other kinds of arguments are analyzed as expressions, and must be 1823unambiguous. The last argument if present must have the identifier 1824@code{Entity} and GNAT verifies that a local name is given. 1825 1826The analyzed pragma is retained in the tree, but not otherwise processed 1827by any part of the GNAT compiler, except to generate corresponding note 1828lines in the generated ALI file. For the format of these note lines, see 1829the compiler source file lib-writ.ads. This pragma is intended for use by 1830external tools, including ASIS. The use of pragma Annotate does not 1831affect the compilation process in any way. This pragma may be used as 1832a configuration pragma. 1833 1834@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1835@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2b} 1836@section Pragma Assert 1837 1838 1839Syntax: 1840 1841@example 1842pragma Assert ( 1843 boolean_EXPRESSION 1844 [, string_EXPRESSION]); 1845@end example 1846 1847The effect of this pragma depends on whether the corresponding command 1848line switch is set to activate assertions. The pragma expands into code 1849equivalent to the following: 1850 1851@example 1852if assertions-enabled then 1853 if not boolean_EXPRESSION then 1854 System.Assertions.Raise_Assert_Failure 1855 (string_EXPRESSION); 1856 end if; 1857end if; 1858@end example 1859 1860The string argument, if given, is the message that will be associated 1861with the exception occurrence if the exception is raised. If no second 1862argument is given, the default message is @code{file}:@code{nnn}, 1863where @code{file} is the name of the source file containing the assert, 1864and @code{nnn} is the line number of the assert. 1865 1866Note that, as with the @code{if} statement to which it is equivalent, the 1867type of the expression is either @code{Standard.Boolean}, or any type derived 1868from this standard type. 1869 1870Assert checks can be either checked or ignored. By default they are ignored. 1871They will be checked if either the command line switch @emph{-gnata} is 1872used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1873to enable @code{Assert_Checks}. 1874 1875If assertions are ignored, then there 1876is no run-time effect (and in particular, any side effects from the 1877expression will not occur at run time). (The expression is still 1878analyzed at compile time, and may cause types to be frozen if they are 1879mentioned here for the first time). 1880 1881If assertions are checked, then the given expression is tested, and if 1882it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1883which results in the raising of @code{Assert_Failure} with the given message. 1884 1885You should generally avoid side effects in the expression arguments of 1886this pragma, because these side effects will turn on and off with the 1887setting of the assertions mode, resulting in assertions that have an 1888effect on the program. However, the expressions are analyzed for 1889semantic correctness whether or not assertions are enabled, so turning 1890assertions on and off cannot affect the legality of a program. 1891 1892Note that the implementation defined policy @code{DISABLE}, given in a 1893pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1894 1895Note: this is a standard language-defined pragma in versions 1896of Ada from 2005 on. In GNAT, it is implemented in all versions 1897of Ada, and the DISABLE policy is an implementation-defined 1898addition. 1899 1900@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1901@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2c} 1902@section Pragma Assert_And_Cut 1903 1904 1905Syntax: 1906 1907@example 1908pragma Assert_And_Cut ( 1909 boolean_EXPRESSION 1910 [, string_EXPRESSION]); 1911@end example 1912 1913The effect of this pragma is identical to that of pragma @code{Assert}, 1914except that in an @code{Assertion_Policy} pragma, the identifier 1915@code{Assert_And_Cut} is used to control whether it is ignored or checked 1916(or disabled). 1917 1918The intention is that this be used within a subprogram when the 1919given test expresion sums up all the work done so far in the 1920subprogram, so that the rest of the subprogram can be verified 1921(informally or formally) using only the entry preconditions, 1922and the expression in this pragma. This allows dividing up 1923a subprogram into sections for the purposes of testing or 1924formal verification. The pragma also serves as useful 1925documentation. 1926 1927@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1928@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2d} 1929@section Pragma Assertion_Policy 1930 1931 1932Syntax: 1933 1934@example 1935pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); 1936 1937pragma Assertion_Policy ( 1938 ASSERTION_KIND => POLICY_IDENTIFIER 1939 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1940 1941ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1942 1943RM_ASSERTION_KIND ::= Assert | 1944 Static_Predicate | 1945 Dynamic_Predicate | 1946 Pre | 1947 Pre'Class | 1948 Post | 1949 Post'Class | 1950 Type_Invariant | 1951 Type_Invariant'Class 1952 1953ID_ASSERTION_KIND ::= Assertions | 1954 Assert_And_Cut | 1955 Assume | 1956 Contract_Cases | 1957 Debug | 1958 Ghost | 1959 Invariant | 1960 Invariant'Class | 1961 Loop_Invariant | 1962 Loop_Variant | 1963 Postcondition | 1964 Precondition | 1965 Predicate | 1966 Refined_Post | 1967 Statement_Assertions 1968 1969POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 1970@end example 1971 1972This is a standard Ada 2012 pragma that is available as an 1973implementation-defined pragma in earlier versions of Ada. 1974The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1975the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1976are implementation defined additions recognized by the GNAT compiler. 1977 1978The pragma applies in both cases to pragmas and aspects with matching 1979names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 1980applies to both the @code{Precondition} pragma 1981and the aspect @code{Precondition}. Note that the identifiers for 1982pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 1983Pre_Class and Post_Class), since these pragmas are intended to be 1984identical to the corresponding aspects). 1985 1986If the policy is @code{CHECK}, then assertions are enabled, i.e. 1987the corresponding pragma or aspect is activated. 1988If the policy is @code{IGNORE}, then assertions are ignored, i.e. 1989the corresponding pragma or aspect is deactivated. 1990This pragma overrides the effect of the @emph{-gnata} switch on the 1991command line. 1992If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, 1993however, if the @emph{-gnatp} switch is specified all assertions are ignored. 1994 1995The implementation defined policy @code{DISABLE} is like 1996@code{IGNORE} except that it completely disables semantic 1997checking of the corresponding pragma or aspect. This is 1998useful when the pragma or aspect argument references subprograms 1999in a with'ed package which is replaced by a dummy package 2000for the final build. 2001 2002The implementation defined assertion kind @code{Assertions} applies to all 2003assertion kinds. The form with no assertion kind given implies this 2004choice, so it applies to all assertion kinds (RM defined, and 2005implementation defined). 2006 2007The implementation defined assertion kind @code{Statement_Assertions} 2008applies to @code{Assert}, @code{Assert_And_Cut}, 2009@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 2010 2011@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 2012@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2e} 2013@section Pragma Assume 2014 2015 2016Syntax: 2017 2018@example 2019pragma Assume ( 2020 boolean_EXPRESSION 2021 [, string_EXPRESSION]); 2022@end example 2023 2024The effect of this pragma is identical to that of pragma @code{Assert}, 2025except that in an @code{Assertion_Policy} pragma, the identifier 2026@code{Assume} is used to control whether it is ignored or checked 2027(or disabled). 2028 2029The intention is that this be used for assumptions about the 2030external environment. So you cannot expect to verify formally 2031or informally that the condition is met, this must be 2032established by examining things outside the program itself. 2033For example, we may have code that depends on the size of 2034@code{Long_Long_Integer} being at least 64. So we could write: 2035 2036@example 2037pragma Assume (Long_Long_Integer'Size >= 64); 2038@end example 2039 2040This assumption cannot be proved from the program itself, 2041but it acts as a useful run-time check that the assumption 2042is met, and documents the need to ensure that it is met by 2043reference to information outside the program. 2044 2045@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 2046@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2f} 2047@section Pragma Assume_No_Invalid_Values 2048 2049 2050@geindex Invalid representations 2051 2052@geindex Invalid values 2053 2054Syntax: 2055 2056@example 2057pragma Assume_No_Invalid_Values (On | Off); 2058@end example 2059 2060This is a configuration pragma that controls the assumptions made by the 2061compiler about the occurrence of invalid representations (invalid values) 2062in the code. 2063 2064The default behavior (corresponding to an Off argument for this pragma), is 2065to assume that values may in general be invalid unless the compiler can 2066prove they are valid. Consider the following example: 2067 2068@example 2069V1 : Integer range 1 .. 10; 2070V2 : Integer range 11 .. 20; 2071... 2072for J in V2 .. V1 loop 2073 ... 2074end loop; 2075@end example 2076 2077if V1 and V2 have valid values, then the loop is known at compile 2078time not to execute since the lower bound must be greater than the 2079upper bound. However in default mode, no such assumption is made, 2080and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 2081is given, the compiler will assume that any occurrence of a variable 2082other than in an explicit @code{'Valid} test always has a valid 2083value, and the loop above will be optimized away. 2084 2085The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 2086you know your code is free of uninitialized variables and other 2087possible sources of invalid representations, and may result in 2088more efficient code. A program that accesses an invalid representation 2089with this pragma in effect is erroneous, so no guarantees can be made 2090about its behavior. 2091 2092It is peculiar though permissible to use this pragma in conjunction 2093with validity checking (-gnatVa). In such cases, accessing invalid 2094values will generally give an exception, though formally the program 2095is erroneous so there are no guarantees that this will always be the 2096case, and it is recommended that these two options not be used together. 2097 2098@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 2099@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30}@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{31} 2100@section Pragma Async_Readers 2101 2102 2103Syntax: 2104 2105@example 2106pragma Asynch_Readers [ (boolean_EXPRESSION) ]; 2107@end example 2108 2109For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in 2110the SPARK 2014 Reference Manual, section 7.1.2. 2111 2112@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 2113@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{32}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{33} 2114@section Pragma Async_Writers 2115 2116 2117Syntax: 2118 2119@example 2120pragma Asynch_Writers [ (boolean_EXPRESSION) ]; 2121@end example 2122 2123For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in 2124the SPARK 2014 Reference Manual, section 7.1.2. 2125 2126@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 2127@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{34} 2128@section Pragma Attribute_Definition 2129 2130 2131Syntax: 2132 2133@example 2134pragma Attribute_Definition 2135 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 2136 [Entity =>] LOCAL_NAME, 2137 [Expression =>] EXPRESSION | NAME); 2138@end example 2139 2140If @code{Attribute} is a known attribute name, this pragma is equivalent to 2141the attribute definition clause: 2142 2143@example 2144for Entity'Attribute use Expression; 2145@end example 2146 2147If @code{Attribute} is not a recognized attribute name, the pragma is 2148ignored, and a warning is emitted. This allows source 2149code to be written that takes advantage of some new attribute, while remaining 2150compilable with earlier compilers. 2151 2152@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 2153@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{35} 2154@section Pragma C_Pass_By_Copy 2155 2156 2157@geindex Passing by copy 2158 2159Syntax: 2160 2161@example 2162pragma C_Pass_By_Copy 2163 ([Max_Size =>] static_integer_EXPRESSION); 2164@end example 2165 2166Normally the default mechanism for passing C convention records to C 2167convention subprograms is to pass them by reference, as suggested by RM 2168B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 2169this default, by requiring that record formal parameters be passed by 2170copy if all of the following conditions are met: 2171 2172 2173@itemize * 2174 2175@item 2176The size of the record type does not exceed the value specified for 2177@code{Max_Size}. 2178 2179@item 2180The record type has @code{Convention C}. 2181 2182@item 2183The formal parameter has this record type, and the subprogram has a 2184foreign (non-Ada) convention. 2185@end itemize 2186 2187If these conditions are met the argument is passed by copy; i.e., in a 2188manner consistent with what C expects if the corresponding formal in the 2189C prototype is a struct (rather than a pointer to a struct). 2190 2191You can also pass records by copy by specifying the convention 2192@code{C_Pass_By_Copy} for the record type, or by using the extended 2193@code{Import} and @code{Export} pragmas, which allow specification of 2194passing mechanisms on a parameter by parameter basis. 2195 2196@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 2197@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{36} 2198@section Pragma Check 2199 2200 2201@geindex Assertions 2202 2203@geindex Named assertions 2204 2205Syntax: 2206 2207@example 2208pragma Check ( 2209 [Name =>] CHECK_KIND, 2210 [Check =>] Boolean_EXPRESSION 2211 [, [Message =>] string_EXPRESSION] ); 2212 2213CHECK_KIND ::= IDENTIFIER | 2214 Pre'Class | 2215 Post'Class | 2216 Type_Invariant'Class | 2217 Invariant'Class 2218@end example 2219 2220This pragma is similar to the predefined pragma @code{Assert} except that an 2221extra identifier argument is present. In conjunction with pragma 2222@code{Check_Policy}, this can be used to define groups of assertions that can 2223be independently controlled. The identifier @code{Assertion} is special, it 2224refers to the normal set of pragma @code{Assert} statements. 2225 2226Checks introduced by this pragma are normally deactivated by default. They can 2227be activated either by the command line option @emph{-gnata}, which turns on 2228all checks, or individually controlled using pragma @code{Check_Policy}. 2229 2230The identifiers @code{Assertions} and @code{Statement_Assertions} are not 2231permitted as check kinds, since this would cause confusion with the use 2232of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 2233pragmas, where they are used to refer to sets of assertions. 2234 2235@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2236@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{37} 2237@section Pragma Check_Float_Overflow 2238 2239 2240@geindex Floating-point overflow 2241 2242Syntax: 2243 2244@example 2245pragma Check_Float_Overflow; 2246@end example 2247 2248In Ada, the predefined floating-point types (@code{Short_Float}, 2249@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 2250defined to be @emph{unconstrained}. This means that even though each 2251has a well-defined base range, an operation that delivers a result 2252outside this base range is not required to raise an exception. 2253This implementation permission accommodates the notion 2254of infinities in IEEE floating-point, and corresponds to the 2255efficient execution mode on most machines. GNAT will not raise 2256overflow exceptions on these machines; instead it will generate 2257infinities and NaN's as defined in the IEEE standard. 2258 2259Generating infinities, although efficient, is not always desirable. 2260Often the preferable approach is to check for overflow, even at the 2261(perhaps considerable) expense of run-time performance. 2262This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 2263range constraints -- and indeed such a subtype 2264can have the same base range as its base type. For example: 2265 2266@example 2267subtype My_Float is Float range Float'Range; 2268@end example 2269 2270Here @code{My_Float} has the same range as 2271@code{Float} but is constrained, so operations on 2272@code{My_Float} values will be checked for overflow 2273against this range. 2274 2275This style will achieve the desired goal, but 2276it is often more convenient to be able to simply use 2277the standard predefined floating-point types as long 2278as overflow checking could be guaranteed. 2279The @code{Check_Float_Overflow} 2280configuration pragma achieves this effect. If a unit is compiled 2281subject to this configuration pragma, then all operations 2282on predefined floating-point types including operations on 2283base types of these floating-point types will be treated as 2284though those types were constrained, and overflow checks 2285will be generated. The @code{Constraint_Error} 2286exception is raised if the result is out of range. 2287 2288This mode can also be set by use of the compiler 2289switch @emph{-gnateF}. 2290 2291@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2292@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{38} 2293@section Pragma Check_Name 2294 2295 2296@geindex Defining check names 2297 2298@geindex Check names 2299@geindex defining 2300 2301Syntax: 2302 2303@example 2304pragma Check_Name (check_name_IDENTIFIER); 2305@end example 2306 2307This is a configuration pragma that defines a new implementation 2308defined check name (unless IDENTIFIER matches one of the predefined 2309check names, in which case the pragma has no effect). Check names 2310are global to a partition, so if two or more configuration pragmas 2311are present in a partition mentioning the same name, only one new 2312check name is introduced. 2313 2314An implementation defined check name introduced with this pragma may 2315be used in only three contexts: @code{pragma Suppress}, 2316@code{pragma Unsuppress}, 2317and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 2318any of these three cases, the check name must be visible. A check 2319name is visible if it is in the configuration pragmas applying to 2320the current unit, or if it appears at the start of any unit that 2321is part of the dependency set of the current unit (e.g., units that 2322are mentioned in @code{with} clauses). 2323 2324Check names introduced by this pragma are subject to control by compiler 2325switches (in particular -gnatp) in the usual manner. 2326 2327@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2328@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{39} 2329@section Pragma Check_Policy 2330 2331 2332@geindex Controlling assertions 2333 2334@geindex Assertions 2335@geindex control 2336 2337@geindex Check pragma control 2338 2339@geindex Named assertions 2340 2341Syntax: 2342 2343@example 2344pragma Check_Policy 2345 ([Name =>] CHECK_KIND, 2346 [Policy =>] POLICY_IDENTIFIER); 2347 2348pragma Check_Policy ( 2349 CHECK_KIND => POLICY_IDENTIFIER 2350 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2351 2352ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2353 2354CHECK_KIND ::= IDENTIFIER | 2355 Pre'Class | 2356 Post'Class | 2357 Type_Invariant'Class | 2358 Invariant'Class 2359 2360The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2361avoids confusion between the two possible syntax forms for this pragma. 2362 2363POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2364@end example 2365 2366This pragma is used to set the checking policy for assertions (specified 2367by aspects or pragmas), the @code{Debug} pragma, or additional checks 2368to be checked using the @code{Check} pragma. It may appear either as 2369a configuration pragma, or within a declarative part of package. In the 2370latter case, it applies from the point where it appears to the end of 2371the declarative region (like pragma @code{Suppress}). 2372 2373The @code{Check_Policy} pragma is similar to the 2374predefined @code{Assertion_Policy} pragma, 2375and if the check kind corresponds to one of the assertion kinds that 2376are allowed by @code{Assertion_Policy}, then the effect is identical. 2377 2378If the first argument is Debug, then the policy applies to Debug pragmas, 2379disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 2380@code{IGNORE}, and allowing them to execute with normal semantics if 2381the policy is @code{ON} or @code{CHECK}. In addition if the policy is 2382@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 2383be totally ignored and not analyzed semantically. 2384 2385Finally the first argument may be some other identifier than the above 2386possibilities, in which case it controls a set of named assertions 2387that can be checked using pragma @code{Check}. For example, if the pragma: 2388 2389@example 2390pragma Check_Policy (Critical_Error, OFF); 2391@end example 2392 2393is given, then subsequent @code{Check} pragmas whose first argument is also 2394@code{Critical_Error} will be disabled. 2395 2396The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 2397to turn on corresponding checks. The default for a set of checks for which no 2398@code{Check_Policy} is given is @code{OFF} unless the compiler switch 2399@emph{-gnata} is given, which turns on all checks by default. 2400 2401The check policy settings @code{CHECK} and @code{IGNORE} are recognized 2402as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 2403compatibility with the standard @code{Assertion_Policy} pragma. The check 2404policy setting @code{DISABLE} causes the second argument of a corresponding 2405@code{Check} pragma to be completely ignored and not analyzed. 2406 2407@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2408@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{3a} 2409@section Pragma Comment 2410 2411 2412Syntax: 2413 2414@example 2415pragma Comment (static_string_EXPRESSION); 2416@end example 2417 2418This is almost identical in effect to pragma @code{Ident}. It allows the 2419placement of a comment into the object file and hence into the 2420executable file if the operating system permits such usage. The 2421difference is that @code{Comment}, unlike @code{Ident}, has 2422no limitations on placement of the pragma (it can be placed 2423anywhere in the main source unit), and if more than one pragma 2424is used, all comments are retained. 2425 2426@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2427@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3b} 2428@section Pragma Common_Object 2429 2430 2431Syntax: 2432 2433@example 2434pragma Common_Object ( 2435 [Internal =>] LOCAL_NAME 2436 [, [External =>] EXTERNAL_SYMBOL] 2437 [, [Size =>] EXTERNAL_SYMBOL] ); 2438 2439EXTERNAL_SYMBOL ::= 2440 IDENTIFIER 2441| static_string_EXPRESSION 2442@end example 2443 2444This pragma enables the shared use of variables stored in overlaid 2445linker areas corresponding to the use of @code{COMMON} 2446in Fortran. The single 2447object @code{LOCAL_NAME} is assigned to the area designated by 2448the @code{External} argument. 2449You may define a record to correspond to a series 2450of fields. The @code{Size} argument 2451is syntax checked in GNAT, but otherwise ignored. 2452 2453@code{Common_Object} is not supported on all platforms. If no 2454support is available, then the code generator will issue a message 2455indicating that the necessary attribute for implementation of this 2456pragma is not available. 2457 2458@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2459@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} 2460@section Pragma Compile_Time_Error 2461 2462 2463Syntax: 2464 2465@example 2466pragma Compile_Time_Error 2467 (boolean_EXPRESSION, static_string_EXPRESSION); 2468@end example 2469 2470This pragma can be used to generate additional compile time 2471error messages. It 2472is particularly useful in generics, where errors can be issued for 2473specific problematic instantiations. The first parameter is a boolean 2474expression. The pragma is effective only if the value of this expression 2475is known at compile time, and has the value True. The set of expressions 2476whose values are known at compile time includes all static boolean 2477expressions, and also other values which the compiler can determine 2478at compile time (e.g., the size of a record type set by an explicit 2479size representation clause, or the value of a variable which was 2480initialized to a constant and is known not to have been modified). 2481If these conditions are met, an error message is generated using 2482the value given as the second argument. This string value may contain 2483embedded ASCII.LF characters to break the message into multiple lines. 2484 2485@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2486@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} 2487@section Pragma Compile_Time_Warning 2488 2489 2490Syntax: 2491 2492@example 2493pragma Compile_Time_Warning 2494 (boolean_EXPRESSION, static_string_EXPRESSION); 2495@end example 2496 2497Same as pragma Compile_Time_Error, except a warning is issued instead 2498of an error message. Note that if this pragma is used in a package that 2499is with'ed by a client, the client will get the warning even though it 2500is issued by a with'ed package (normally warnings in with'ed units are 2501suppressed, but this is a special exception to that rule). 2502 2503One typical use is within a generic where compile time known characteristics 2504of formal parameters are tested, and warnings given appropriately. Another use 2505with a first parameter of True is to warn a client about use of a package, 2506for example that it is not fully implemented. 2507 2508@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2509@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3e} 2510@section Pragma Compiler_Unit 2511 2512 2513Syntax: 2514 2515@example 2516pragma Compiler_Unit; 2517@end example 2518 2519This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2520retained so that old versions of the GNAT run-time that use this pragma can 2521be compiled with newer versions of the compiler. 2522 2523@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2524@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3f} 2525@section Pragma Compiler_Unit_Warning 2526 2527 2528Syntax: 2529 2530@example 2531pragma Compiler_Unit_Warning; 2532@end example 2533 2534This pragma is intended only for internal use in the GNAT run-time library. 2535It indicates that the unit is used as part of the compiler build. The effect 2536is to generate warnings for the use of constructs (for example, conditional 2537expressions) that would cause trouble when bootstrapping using an older 2538version of GNAT. For the exact list of restrictions, see the compiler sources 2539and references to Check_Compiler_Unit. 2540 2541@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2542@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{40} 2543@section Pragma Complete_Representation 2544 2545 2546Syntax: 2547 2548@example 2549pragma Complete_Representation; 2550@end example 2551 2552This pragma must appear immediately within a record representation 2553clause. Typical placements are before the first component clause 2554or after the last component clause. The effect is to give an error 2555message if any component is missing a component clause. This pragma 2556may be used to ensure that a record representation clause is 2557complete, and that this invariant is maintained if fields are 2558added to the record in the future. 2559 2560@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2561@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{41} 2562@section Pragma Complex_Representation 2563 2564 2565Syntax: 2566 2567@example 2568pragma Complex_Representation 2569 ([Entity =>] LOCAL_NAME); 2570@end example 2571 2572The @code{Entity} argument must be the name of a record type which has 2573two fields of the same floating-point type. The effect of this pragma is 2574to force gcc to use the special internal complex representation form for 2575this record, which may be more efficient. Note that this may result in 2576the code for this type not conforming to standard ABI (application 2577binary interface) requirements for the handling of record types. For 2578example, in some environments, there is a requirement for passing 2579records by pointer, and the use of this pragma may result in passing 2580this type in floating-point registers. 2581 2582@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2583@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{42} 2584@section Pragma Component_Alignment 2585 2586 2587@geindex Alignments of components 2588 2589@geindex Pragma Component_Alignment 2590 2591Syntax: 2592 2593@example 2594pragma Component_Alignment ( 2595 [Form =>] ALIGNMENT_CHOICE 2596 [, [Name =>] type_LOCAL_NAME]); 2597 2598ALIGNMENT_CHOICE ::= 2599 Component_Size 2600| Component_Size_4 2601| Storage_Unit 2602| Default 2603@end example 2604 2605Specifies the alignment of components in array or record types. 2606The meaning of the @code{Form} argument is as follows: 2607 2608@quotation 2609 2610@geindex Component_Size (in pragma Component_Alignment) 2611@end quotation 2612 2613 2614@table @asis 2615 2616@item @emph{Component_Size} 2617 2618Aligns scalar components and subcomponents of the array or record type 2619on boundaries appropriate to their inherent size (naturally 2620aligned). For example, 1-byte components are aligned on byte boundaries, 26212-byte integer components are aligned on 2-byte boundaries, 4-byte 2622integer components are aligned on 4-byte boundaries and so on. These 2623alignment rules correspond to the normal rules for C compilers on all 2624machines except the VAX. 2625 2626@geindex Component_Size_4 (in pragma Component_Alignment) 2627 2628@item @emph{Component_Size_4} 2629 2630Naturally aligns components with a size of four or fewer 2631bytes. Components that are larger than 4 bytes are placed on the next 26324-byte boundary. 2633 2634@geindex Storage_Unit (in pragma Component_Alignment) 2635 2636@item @emph{Storage_Unit} 2637 2638Specifies that array or record components are byte aligned, i.e., 2639aligned on boundaries determined by the value of the constant 2640@code{System.Storage_Unit}. 2641 2642@geindex Default (in pragma Component_Alignment) 2643 2644@item @emph{Default} 2645 2646Specifies that array or record components are aligned on default 2647boundaries, appropriate to the underlying hardware or operating system or 2648both. The @code{Default} choice is the same as @code{Component_Size} (natural 2649alignment). 2650@end table 2651 2652If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must 2653refer to a local record or array type, and the specified alignment 2654choice applies to the specified type. The use of 2655@code{Component_Alignment} together with a pragma @code{Pack} causes the 2656@code{Component_Alignment} pragma to be ignored. The use of 2657@code{Component_Alignment} together with a record representation clause 2658is only effective for fields not specified by the representation clause. 2659 2660If the @code{Name} parameter is absent, the pragma can be used as either 2661a configuration pragma, in which case it applies to one or more units in 2662accordance with the normal rules for configuration pragmas, or it can be 2663used within a declarative part, in which case it applies to types that 2664are declared within this declarative part, or within any nested scope 2665within this declarative part. In either case it specifies the alignment 2666to be applied to any record or array type which has otherwise standard 2667representation. 2668 2669If the alignment for a record or array type is not specified (using 2670pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2671clause), the GNAT uses the default alignment as described previously. 2672 2673@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2674@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{44} 2675@section Pragma Constant_After_Elaboration 2676 2677 2678Syntax: 2679 2680@example 2681pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2682@end example 2683 2684For the semantics of this pragma, see the entry for aspect 2685@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2686 2687@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2688@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{45}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{46} 2689@section Pragma Contract_Cases 2690 2691 2692@geindex Contract cases 2693 2694Syntax: 2695 2696@example 2697pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2698 2699CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2700 2701CASE_GUARD ::= boolean_EXPRESSION | others 2702 2703CONSEQUENCE ::= boolean_EXPRESSION 2704@end example 2705 2706The @code{Contract_Cases} pragma allows defining fine-grain specifications 2707that can complement or replace the contract given by a precondition and a 2708postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2709by testing and formal verification tools. The compiler checks its validity and, 2710depending on the assertion policy at the point of declaration of the pragma, 2711it may insert a check in the executable. For code generation, the contract 2712cases 2713 2714@example 2715pragma Contract_Cases ( 2716 Cond1 => Pred1, 2717 Cond2 => Pred2); 2718@end example 2719 2720are equivalent to 2721 2722@example 2723C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2724C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2725pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2726pragma Postcondition (if C1 then Pred1); 2727pragma Postcondition (if C2 then Pred2); 2728@end example 2729 2730The precondition ensures that one and only one of the case guards is 2731satisfied on entry to the subprogram. 2732The postcondition ensures that for the case guard that was True on entry, 2733the corrresponding consequence is True on exit. Other consequence expressions 2734are not evaluated. 2735 2736A precondition @code{P} and postcondition @code{Q} can also be 2737expressed as contract cases: 2738 2739@example 2740pragma Contract_Cases (P => Q); 2741@end example 2742 2743The placement and visibility rules for @code{Contract_Cases} pragmas are 2744identical to those described for preconditions and postconditions. 2745 2746The compiler checks that boolean expressions given in case guards and 2747consequences are valid, where the rules for case guards are the same as 2748the rule for an expression in @code{Precondition} and the rules for 2749consequences are the same as the rule for an expression in 2750@code{Postcondition}. In particular, attributes @code{'Old} and 2751@code{'Result} can only be used within consequence expressions. 2752The case guard for the last contract case may be @code{others}, to denote 2753any case not captured by the previous cases. The 2754following is an example of use within a package spec: 2755 2756@example 2757package Math_Functions is 2758 ... 2759 function Sqrt (Arg : Float) return Float; 2760 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 2761 Arg >= 100.0 => Sqrt'Result >= 10.0, 2762 others => Sqrt'Result = 0.0)); 2763 ... 2764end Math_Functions; 2765@end example 2766 2767The meaning of contract cases is that only one case should apply at each 2768call, as determined by the corresponding case guard evaluating to True, 2769and that the consequence for this case should hold when the subprogram 2770returns. 2771 2772@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2773@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{47} 2774@section Pragma Convention_Identifier 2775 2776 2777@geindex Conventions 2778@geindex synonyms 2779 2780Syntax: 2781 2782@example 2783pragma Convention_Identifier ( 2784 [Name =>] IDENTIFIER, 2785 [Convention =>] convention_IDENTIFIER); 2786@end example 2787 2788This pragma provides a mechanism for supplying synonyms for existing 2789convention identifiers. The @code{Name} identifier can subsequently 2790be used as a synonym for the given convention in other pragmas (including 2791for example pragma @code{Import} or another @code{Convention_Identifier} 2792pragma). As an example of the use of this, suppose you had legacy code 2793which used Fortran77 as the identifier for Fortran. Then the pragma: 2794 2795@example 2796pragma Convention_Identifier (Fortran77, Fortran); 2797@end example 2798 2799would allow the use of the convention identifier @code{Fortran77} in 2800subsequent code, avoiding the need to modify the sources. As another 2801example, you could use this to parameterize convention requirements 2802according to systems. Suppose you needed to use @code{Stdcall} on 2803windows systems, and @code{C} on some other system, then you could 2804define a convention identifier @code{Library} and use a single 2805@code{Convention_Identifier} pragma to specify which convention 2806would be used system-wide. 2807 2808@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2809@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{48} 2810@section Pragma CPP_Class 2811 2812 2813@geindex Interfacing with C++ 2814 2815Syntax: 2816 2817@example 2818pragma CPP_Class ([Entity =>] LOCAL_NAME); 2819@end example 2820 2821The argument denotes an entity in the current declarative region that is 2822declared as a record type. It indicates that the type corresponds to an 2823externally declared C++ class type, and is to be laid out the same way 2824that C++ would lay out the type. If the C++ class has virtual primitives 2825then the record must be declared as a tagged record type. 2826 2827Types for which @code{CPP_Class} is specified do not have assignment or 2828equality operators defined (such operations can be imported or declared 2829as subprograms as required). Initialization is allowed only by constructor 2830functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2831limited if not explicitly declared as limited or derived from a limited 2832type, and an error is issued in that case. 2833 2834See @ref{49,,Interfacing to C++} for related information. 2835 2836Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2837for backward compatibility but its functionality is available 2838using pragma @code{Import} with @code{Convention} = @code{CPP}. 2839 2840@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2841@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{4a} 2842@section Pragma CPP_Constructor 2843 2844 2845@geindex Interfacing with C++ 2846 2847Syntax: 2848 2849@example 2850pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2851 [, [External_Name =>] static_string_EXPRESSION ] 2852 [, [Link_Name =>] static_string_EXPRESSION ]); 2853@end example 2854 2855This pragma identifies an imported function (imported in the usual way 2856with pragma @code{Import}) as corresponding to a C++ constructor. If 2857@code{External_Name} and @code{Link_Name} are not specified then the 2858@code{Entity} argument is a name that must have been previously mentioned 2859in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2860must be of one of the following forms: 2861 2862 2863@itemize * 2864 2865@item 2866@strong{function} @code{Fname} @strong{return} T` 2867 2868@item 2869@strong{function} @code{Fname} @strong{return} T'Class 2870 2871@item 2872@strong{function} @code{Fname} (...) @strong{return} T` 2873 2874@item 2875@strong{function} @code{Fname} (...) @strong{return} T'Class 2876@end itemize 2877 2878where @code{T} is a limited record type imported from C++ with pragma 2879@code{Import} and @code{Convention} = @code{CPP}. 2880 2881The first two forms import the default constructor, used when an object 2882of type @code{T} is created on the Ada side with no explicit constructor. 2883The latter two forms cover all the non-default constructors of the type. 2884See the GNAT User's Guide for details. 2885 2886If no constructors are imported, it is impossible to create any objects 2887on the Ada side and the type is implicitly declared abstract. 2888 2889Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2890using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2891GCC switch). 2892See @ref{49,,Interfacing to C++} for more related information. 2893 2894Note: The use of functions returning class-wide types for constructors is 2895currently obsolete. They are supported for backward compatibility. The 2896use of functions returning the type T leave the Ada sources more clear 2897because the imported C++ constructors always return an object of type T; 2898that is, they never return an object whose type is a descendant of type T. 2899 2900@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2901@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{4b} 2902@section Pragma CPP_Virtual 2903 2904 2905@geindex Interfacing to C++ 2906 2907This pragma is now obsolete and, other than generating a warning if warnings 2908on obsolescent features are enabled, is completely ignored. 2909It is retained for compatibility 2910purposes. It used to be required to ensure compoatibility with C++, but 2911is no longer required for that purpose because GNAT generates 2912the same object layout as the G++ compiler by default. 2913 2914See @ref{49,,Interfacing to C++} for related information. 2915 2916@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2917@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4c} 2918@section Pragma CPP_Vtable 2919 2920 2921@geindex Interfacing with C++ 2922 2923This pragma is now obsolete and, other than generating a warning if warnings 2924on obsolescent features are enabled, is completely ignored. 2925It used to be required to ensure compatibility with C++, but 2926is no longer required for that purpose because GNAT generates 2927the same object layout as the G++ compiler by default. 2928 2929See @ref{49,,Interfacing to C++} for related information. 2930 2931@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas 2932@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4d} 2933@section Pragma CPU 2934 2935 2936Syntax: 2937 2938@example 2939pragma CPU (EXPRESSION); 2940@end example 2941 2942This pragma is standard in Ada 2012, but is available in all earlier 2943versions of Ada as an implementation-defined pragma. 2944See Ada 2012 Reference Manual for details. 2945 2946@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas 2947@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4e} 2948@section Pragma Deadline_Floor 2949 2950 2951Syntax: 2952 2953@example 2954pragma Deadline_Floor (time_span_EXPRESSION); 2955@end example 2956 2957This pragma applies only to protected types and specifies the floor 2958deadline inherited by a task when the task enters a protected object. 2959It is effective only when the EDF scheduling policy is used. 2960 2961@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas 2962@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4f}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{50} 2963@section Pragma Default_Initial_Condition 2964 2965 2966Syntax: 2967 2968@example 2969pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2970@end example 2971 2972For the semantics of this pragma, see the entry for aspect 2973@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2974 2975@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2976@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{51} 2977@section Pragma Debug 2978 2979 2980Syntax: 2981 2982@example 2983pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2984 2985PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2986 PROCEDURE_NAME 2987| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2988@end example 2989 2990The procedure call argument has the syntactic form of an expression, meeting 2991the syntactic requirements for pragmas. 2992 2993If debug pragmas are not enabled or if the condition is present and evaluates 2994to False, this pragma has no effect. If debug pragmas are enabled, the 2995semantics of the pragma is exactly equivalent to the procedure call statement 2996corresponding to the argument with a terminating semicolon. Pragmas are 2997permitted in sequences of declarations, so you can use pragma @code{Debug} to 2998intersperse calls to debug procedures in the middle of declarations. Debug 2999pragmas can be enabled either by use of the command line switch @emph{-gnata} 3000or by use of the pragma @code{Check_Policy} with a first argument of 3001@code{Debug}. 3002 3003@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 3004@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{52} 3005@section Pragma Debug_Policy 3006 3007 3008Syntax: 3009 3010@example 3011pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 3012@end example 3013 3014This pragma is equivalent to a corresponding @code{Check_Policy} pragma 3015with a first argument of @code{Debug}. It is retained for historical 3016compatibility reasons. 3017 3018@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 3019@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{53} 3020@section Pragma Default_Scalar_Storage_Order 3021 3022 3023@geindex Default_Scalar_Storage_Order 3024 3025@geindex Scalar_Storage_Order 3026 3027Syntax: 3028 3029@example 3030pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 3031@end example 3032 3033Normally if no explicit @code{Scalar_Storage_Order} is given for a record 3034type or array type, then the scalar storage order defaults to the ordinary 3035default for the target. But this default may be overridden using this pragma. 3036The pragma may appear as a configuration pragma, or locally within a package 3037spec or declarative part. In the latter case, it applies to all subsequent 3038types declared within that package spec or declarative part. 3039 3040The following example shows the use of this pragma: 3041 3042@example 3043pragma Default_Scalar_Storage_Order (High_Order_First); 3044with System; use System; 3045package DSSO1 is 3046 type H1 is record 3047 a : Integer; 3048 end record; 3049 3050 type L2 is record 3051 a : Integer; 3052 end record; 3053 for L2'Scalar_Storage_Order use Low_Order_First; 3054 3055 type L2a is new L2; 3056 3057 package Inner is 3058 type H3 is record 3059 a : Integer; 3060 end record; 3061 3062 pragma Default_Scalar_Storage_Order (Low_Order_First); 3063 3064 type L4 is record 3065 a : Integer; 3066 end record; 3067 end Inner; 3068 3069 type H4a is new Inner.L4; 3070 3071 type H5 is record 3072 a : Integer; 3073 end record; 3074end DSSO1; 3075@end example 3076 3077In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar 3078storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. 3079Note that in the case of @code{H4a}, the order is not inherited 3080from the parent type. Only an explicitly set @code{Scalar_Storage_Order} 3081gets inherited on type derivation. 3082 3083If this pragma is used as a configuration pragma which appears within a 3084configuration pragma file (as opposed to appearing explicitly at the start 3085of a single unit), then the binder will require that all units in a partition 3086be compiled in a similar manner, other than run-time units, which are not 3087affected by this pragma. Note that the use of this form is discouraged because 3088it may significantly degrade the run-time performance of the software, instead 3089the default scalar storage order ought to be changed only on a local basis. 3090 3091@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 3092@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{54} 3093@section Pragma Default_Storage_Pool 3094 3095 3096@geindex Default_Storage_Pool 3097 3098Syntax: 3099 3100@example 3101pragma Default_Storage_Pool (storage_pool_NAME | null); 3102@end example 3103 3104This pragma is standard in Ada 2012, but is available in all earlier 3105versions of Ada as an implementation-defined pragma. 3106See Ada 2012 Reference Manual for details. 3107 3108@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 3109@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{55}@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{56} 3110@section Pragma Depends 3111 3112 3113Syntax: 3114 3115@example 3116pragma Depends (DEPENDENCY_RELATION); 3117 3118DEPENDENCY_RELATION ::= 3119 null 3120 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 3121 3122DEPENDENCY_CLAUSE ::= 3123 OUTPUT_LIST =>[+] INPUT_LIST 3124 | NULL_DEPENDENCY_CLAUSE 3125 3126NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 3127 3128OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 3129 3130INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 3131 3132OUTPUT ::= NAME | FUNCTION_RESULT 3133INPUT ::= NAME 3134 3135where FUNCTION_RESULT is a function Result attribute_reference 3136@end example 3137 3138For the semantics of this pragma, see the entry for aspect @code{Depends} in the 3139SPARK 2014 Reference Manual, section 6.1.5. 3140 3141@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 3142@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{57} 3143@section Pragma Detect_Blocking 3144 3145 3146Syntax: 3147 3148@example 3149pragma Detect_Blocking; 3150@end example 3151 3152This is a standard pragma in Ada 2005, that is available in all earlier 3153versions of Ada as an implementation-defined pragma. 3154 3155This is a configuration pragma that forces the detection of potentially 3156blocking operations within a protected operation, and to raise Program_Error 3157if that happens. 3158 3159@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 3160@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{58} 3161@section Pragma Disable_Atomic_Synchronization 3162 3163 3164@geindex Atomic Synchronization 3165 3166Syntax: 3167 3168@example 3169pragma Disable_Atomic_Synchronization [(Entity)]; 3170@end example 3171 3172Ada requires that accesses (reads or writes) of an atomic variable be 3173regarded as synchronization points in the case of multiple tasks. 3174Particularly in the case of multi-processors this may require special 3175handling, e.g. the generation of memory barriers. This capability may 3176be turned off using this pragma in cases where it is known not to be 3177required. 3178 3179The placement and scope rules for this pragma are the same as those 3180for @code{pragma Suppress}. In particular it can be used as a 3181configuration pragma, or in a declaration sequence where it applies 3182till the end of the scope. If an @code{Entity} argument is present, 3183the action applies only to that entity. 3184 3185@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 3186@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{59} 3187@section Pragma Dispatching_Domain 3188 3189 3190Syntax: 3191 3192@example 3193pragma Dispatching_Domain (EXPRESSION); 3194@end example 3195 3196This pragma is standard in Ada 2012, but is available in all earlier 3197versions of Ada as an implementation-defined pragma. 3198See Ada 2012 Reference Manual for details. 3199 3200@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 3201@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5b} 3202@section Pragma Effective_Reads 3203 3204 3205Syntax: 3206 3207@example 3208pragma Effective_Reads [ (boolean_EXPRESSION) ]; 3209@end example 3210 3211For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in 3212the SPARK 2014 Reference Manual, section 7.1.2. 3213 3214@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3215@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5c}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5d} 3216@section Pragma Effective_Writes 3217 3218 3219Syntax: 3220 3221@example 3222pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3223@end example 3224 3225For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} 3226in the SPARK 2014 Reference Manual, section 7.1.2. 3227 3228@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3229@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5e} 3230@section Pragma Elaboration_Checks 3231 3232 3233@geindex Elaboration control 3234 3235Syntax: 3236 3237@example 3238pragma Elaboration_Checks (Dynamic | Static); 3239@end example 3240 3241This is a configuration pragma which specifies the elaboration model to be 3242used during compilation. For more information on the elaboration models of 3243GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User's 3244Guide}. 3245 3246The pragma may appear in the following contexts: 3247 3248 3249@itemize * 3250 3251@item 3252Configuration pragmas file 3253 3254@item 3255Prior to the context clauses of a compilation unit's initial declaration 3256@end itemize 3257 3258Any other placement of the pragma will result in a warning and the effects of 3259the offending pragma will be ignored. 3260 3261If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in 3262effect. If the pragma argument is @code{Static}, then the static elaboration model 3263is in effect. 3264 3265@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3266@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5f} 3267@section Pragma Eliminate 3268 3269 3270@geindex Elimination of unused subprograms 3271 3272Syntax: 3273 3274@example 3275pragma Eliminate ( 3276 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 3277 [ Entity => ] IDENTIFIER | 3278 SELECTED_COMPONENT | 3279 STRING_LITERAL 3280 [, Source_Location => SOURCE_TRACE ] ); 3281 3282 SOURCE_TRACE ::= STRING_LITERAL 3283@end example 3284 3285This pragma indicates that the given entity is not used in the program to be 3286compiled and built, thus allowing the compiler to 3287eliminate the code or data associated with the named entity. Any reference to 3288an eliminated entity causes a compile-time or link-time error. 3289 3290The pragma has the following semantics, where @code{U} is the unit specified by 3291the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} 3292argument: 3293 3294 3295@itemize * 3296 3297@item 3298@code{E} must be a subprogram that is explicitly declared either: 3299 3300o Within @code{U}, or 3301 3302o Within a generic package that is instantiated in @code{U}, or 3303 3304o As an instance of generic subprogram instantiated in @code{U}. 3305 3306Otherwise the pragma is ignored. 3307 3308@item 3309If @code{E} is overloaded within @code{U} then, in the absence of a 3310@code{Source_Location} argument, all overloadings are eliminated. 3311 3312@item 3313If @code{E} is overloaded within @code{U} and only some overloadings 3314are to be eliminated, then each overloading to be eliminated 3315must be specified in a corresponding pragma @code{Eliminate} 3316with a @code{Source_Location} argument identifying the line where the 3317declaration appears, as described below. 3318 3319@item 3320If @code{E} is declared as the result of a generic instantiation, then 3321a @code{Source_Location} argument is needed, as described below 3322@end itemize 3323 3324Pragma @code{Eliminate} allows a program to be compiled in a system-independent 3325manner, so that unused entities are eliminated but without 3326needing to modify the source text. Normally the required set of 3327@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. 3328 3329Any source file change that removes, splits, or 3330adds lines may make the set of @code{Eliminate} pragmas invalid because their 3331@code{Source_Location} argument values may get out of date. 3332 3333Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 3334operation. In this case all the subprograms to which the given operation can 3335dispatch are considered to be unused (are never called as a result of a direct 3336or a dispatching call). 3337 3338The string literal given for the source location specifies the line number 3339of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: 3340 3341@example 3342SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 3343 3344LBRACKET ::= '[' 3345RBRACKET ::= ']' 3346 3347SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3348 3349LINE_NUMBER ::= DIGIT @{DIGIT@} 3350@end example 3351 3352Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. 3353 3354The source trace that is given as the @code{Source_Location} must obey the 3355following rules (or else the pragma is ignored), where @code{U} is 3356the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the 3357subprogram specified by the @code{Entity} argument: 3358 3359 3360@itemize * 3361 3362@item 3363@code{FILE_NAME} is the short name (with no directory 3364information) of the Ada source file for @code{U}, using the required syntax 3365for the underlying file system (e.g. case is significant if the underlying 3366operating system is case sensitive). 3367If @code{U} is a package and @code{E} is a subprogram declared in the package 3368specification and its full declaration appears in the package body, 3369then the relevant source file is the one for the package specification; 3370analogously if @code{U} is a generic package. 3371 3372@item 3373If @code{E} is not declared in a generic instantiation (this includes 3374generic subprogram instances), the source trace includes only one source 3375line reference. @code{LINE_NUMBER} gives the line number of the occurrence 3376of the declaration of @code{E} within the source file (as a decimal literal 3377without an exponent or point). 3378 3379@item 3380If @code{E} is declared by a generic instantiation, its source trace 3381(from left to right) starts with the source location of the 3382declaration of @code{E} in the generic unit and ends with the source 3383location of the instantiation, given in square brackets. This approach is 3384applied recursively with nested instantiations: the rightmost (nested 3385most deeply in square brackets) element of the source trace is the location 3386of the outermost instantiation, and the leftmost element (that is, outside 3387of any square brackets) is the location of the declaration of @code{E} in 3388the generic unit. 3389@end itemize 3390 3391Examples: 3392 3393@quotation 3394 3395@example 3396pragma Eliminate (Pkg0, Proc); 3397-- Eliminate (all overloadings of) Proc in Pkg0 3398 3399pragma Eliminate (Pkg1, Proc, 3400 Source_Location => "pkg1.ads:8"); 3401-- Eliminate overloading of Proc at line 8 in pkg1.ads 3402 3403-- Assume the following file contents: 3404-- gen_pkg.ads 3405-- 1: generic 3406-- 2: type T is private; 3407-- 3: package Gen_Pkg is 3408-- 4: procedure Proc(N : T); 3409-- ... ... 3410-- ... end Gen_Pkg; 3411-- 3412-- q.adb 3413-- 1: with Gen_Pkg; 3414-- 2: procedure Q is 3415-- 3: package Inst_Pkg is new Gen_Pkg(Integer); 3416-- ... -- No calls on Inst_Pkg.Proc 3417-- ... end Q; 3418 3419-- The following pragma eliminates Inst_Pkg.Proc from Q 3420pragma Eliminate (Q, Proc, 3421 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 3422@end example 3423@end quotation 3424 3425@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3426@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{60} 3427@section Pragma Enable_Atomic_Synchronization 3428 3429 3430@geindex Atomic Synchronization 3431 3432Syntax: 3433 3434@example 3435pragma Enable_Atomic_Synchronization [(Entity)]; 3436@end example 3437 3438Ada requires that accesses (reads or writes) of an atomic variable be 3439regarded as synchronization points in the case of multiple tasks. 3440Particularly in the case of multi-processors this may require special 3441handling, e.g. the generation of memory barriers. This synchronization 3442is performed by default, but can be turned off using 3443@code{pragma Disable_Atomic_Synchronization}. The 3444@code{Enable_Atomic_Synchronization} pragma can be used to turn 3445it back on. 3446 3447The placement and scope rules for this pragma are the same as those 3448for @code{pragma Unsuppress}. In particular it can be used as a 3449configuration pragma, or in a declaration sequence where it applies 3450till the end of the scope. If an @code{Entity} argument is present, 3451the action applies only to that entity. 3452 3453@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3454@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{61} 3455@section Pragma Export_Function 3456 3457 3458@geindex Argument passing mechanisms 3459 3460Syntax: 3461 3462@example 3463pragma Export_Function ( 3464 [Internal =>] LOCAL_NAME 3465 [, [External =>] EXTERNAL_SYMBOL] 3466 [, [Parameter_Types =>] PARAMETER_TYPES] 3467 [, [Result_Type =>] result_SUBTYPE_MARK] 3468 [, [Mechanism =>] MECHANISM] 3469 [, [Result_Mechanism =>] MECHANISM_NAME]); 3470 3471EXTERNAL_SYMBOL ::= 3472 IDENTIFIER 3473| static_string_EXPRESSION 3474| "" 3475 3476PARAMETER_TYPES ::= 3477 null 3478| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3479 3480TYPE_DESIGNATOR ::= 3481 subtype_NAME 3482| subtype_Name ' Access 3483 3484MECHANISM ::= 3485 MECHANISM_NAME 3486| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3487 3488MECHANISM_ASSOCIATION ::= 3489 [formal_parameter_NAME =>] MECHANISM_NAME 3490 3491MECHANISM_NAME ::= Value | Reference 3492@end example 3493 3494Use this pragma to make a function externally callable and optionally 3495provide information on mechanisms to be used for passing parameter and 3496result values. We recommend, for the purposes of improving portability, 3497this pragma always be used in conjunction with a separate pragma 3498@code{Export}, which must precede the pragma @code{Export_Function}. 3499GNAT does not require a separate pragma @code{Export}, but if none is 3500present, @code{Convention Ada} is assumed, which is usually 3501not what is wanted, so it is usually appropriate to use this 3502pragma in conjunction with a @code{Export} or @code{Convention} 3503pragma that specifies the desired foreign convention. 3504Pragma @code{Export_Function} 3505(and @code{Export}, if present) must appear in the same declarative 3506region as the function to which they apply. 3507 3508The @code{internal_name} must uniquely designate the function to which the 3509pragma applies. If more than one function name exists of this name in 3510the declarative part you must use the @code{Parameter_Types} and 3511@code{Result_Type} parameters to achieve the required 3512unique designation. The @cite{subtype_mark}s in these parameters must 3513exactly match the subtypes in the corresponding function specification, 3514using positional notation to match parameters with subtype marks. 3515The form with an @code{'Access} attribute can be used to match an 3516anonymous access parameter. 3517 3518@geindex Suppressing external name 3519 3520Special treatment is given if the EXTERNAL is an explicit null 3521string or a static string expressions that evaluates to the null 3522string. In this case, no external name is generated. This form 3523still allows the specification of parameter mechanisms. 3524 3525@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3526@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{62} 3527@section Pragma Export_Object 3528 3529 3530Syntax: 3531 3532@example 3533pragma Export_Object 3534 [Internal =>] LOCAL_NAME 3535 [, [External =>] EXTERNAL_SYMBOL] 3536 [, [Size =>] EXTERNAL_SYMBOL] 3537 3538EXTERNAL_SYMBOL ::= 3539 IDENTIFIER 3540| static_string_EXPRESSION 3541@end example 3542 3543This pragma designates an object as exported, and apart from the 3544extended rules for external symbols, is identical in effect to the use of 3545the normal @code{Export} pragma applied to an object. You may use a 3546separate Export pragma (and you probably should from the point of view 3547of portability), but it is not required. @code{Size} is syntax checked, 3548but otherwise ignored by GNAT. 3549 3550@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas 3551@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{63} 3552@section Pragma Export_Procedure 3553 3554 3555Syntax: 3556 3557@example 3558pragma Export_Procedure ( 3559 [Internal =>] LOCAL_NAME 3560 [, [External =>] EXTERNAL_SYMBOL] 3561 [, [Parameter_Types =>] PARAMETER_TYPES] 3562 [, [Mechanism =>] MECHANISM]); 3563 3564EXTERNAL_SYMBOL ::= 3565 IDENTIFIER 3566| static_string_EXPRESSION 3567| "" 3568 3569PARAMETER_TYPES ::= 3570 null 3571| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3572 3573TYPE_DESIGNATOR ::= 3574 subtype_NAME 3575| subtype_Name ' Access 3576 3577MECHANISM ::= 3578 MECHANISM_NAME 3579| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3580 3581MECHANISM_ASSOCIATION ::= 3582 [formal_parameter_NAME =>] MECHANISM_NAME 3583 3584MECHANISM_NAME ::= Value | Reference 3585@end example 3586 3587This pragma is identical to @code{Export_Function} except that it 3588applies to a procedure rather than a function and the parameters 3589@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3590GNAT does not require a separate pragma @code{Export}, but if none is 3591present, @code{Convention Ada} is assumed, which is usually 3592not what is wanted, so it is usually appropriate to use this 3593pragma in conjunction with a @code{Export} or @code{Convention} 3594pragma that specifies the desired foreign convention. 3595 3596@geindex Suppressing external name 3597 3598Special treatment is given if the EXTERNAL is an explicit null 3599string or a static string expressions that evaluates to the null 3600string. In this case, no external name is generated. This form 3601still allows the specification of parameter mechanisms. 3602 3603@node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas 3604@anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{64} 3605@section Pragma Export_Value 3606 3607 3608Syntax: 3609 3610@example 3611pragma Export_Value ( 3612 [Value =>] static_integer_EXPRESSION, 3613 [Link_Name =>] static_string_EXPRESSION); 3614@end example 3615 3616This pragma serves to export a static integer value for external use. 3617The first argument specifies the value to be exported. The Link_Name 3618argument specifies the symbolic name to be associated with the integer 3619value. This pragma is useful for defining a named static value in Ada 3620that can be referenced in assembly language units to be linked with 3621the application. This pragma is currently supported only for the 3622AAMP target and is ignored for other targets. 3623 3624@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas 3625@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{65} 3626@section Pragma Export_Valued_Procedure 3627 3628 3629Syntax: 3630 3631@example 3632pragma Export_Valued_Procedure ( 3633 [Internal =>] LOCAL_NAME 3634 [, [External =>] EXTERNAL_SYMBOL] 3635 [, [Parameter_Types =>] PARAMETER_TYPES] 3636 [, [Mechanism =>] MECHANISM]); 3637 3638EXTERNAL_SYMBOL ::= 3639 IDENTIFIER 3640| static_string_EXPRESSION 3641| "" 3642 3643PARAMETER_TYPES ::= 3644 null 3645| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3646 3647TYPE_DESIGNATOR ::= 3648 subtype_NAME 3649| subtype_Name ' Access 3650 3651MECHANISM ::= 3652 MECHANISM_NAME 3653| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3654 3655MECHANISM_ASSOCIATION ::= 3656 [formal_parameter_NAME =>] MECHANISM_NAME 3657 3658MECHANISM_NAME ::= Value | Reference 3659@end example 3660 3661This pragma is identical to @code{Export_Procedure} except that the 3662first parameter of @code{LOCAL_NAME}, which must be present, must be of 3663mode @code{out}, and externally the subprogram is treated as a function 3664with this parameter as the result of the function. GNAT provides for 3665this capability to allow the use of @code{out} and @code{in out} 3666parameters in interfacing to external functions (which are not permitted 3667in Ada functions). 3668GNAT does not require a separate pragma @code{Export}, but if none is 3669present, @code{Convention Ada} is assumed, which is almost certainly 3670not what is wanted since the whole point of this pragma is to interface 3671with foreign language functions, so it is usually appropriate to use this 3672pragma in conjunction with a @code{Export} or @code{Convention} 3673pragma that specifies the desired foreign convention. 3674 3675@geindex Suppressing external name 3676 3677Special treatment is given if the EXTERNAL is an explicit null 3678string or a static string expressions that evaluates to the null 3679string. In this case, no external name is generated. This form 3680still allows the specification of parameter mechanisms. 3681 3682@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3683@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{66} 3684@section Pragma Extend_System 3685 3686 3687@geindex System 3688@geindex extending 3689 3690@geindex DEC Ada 83 3691 3692Syntax: 3693 3694@example 3695pragma Extend_System ([Name =>] IDENTIFIER); 3696@end example 3697 3698This pragma is used to provide backwards compatibility with other 3699implementations that extend the facilities of package @code{System}. In 3700GNAT, @code{System} contains only the definitions that are present in 3701the Ada RM. However, other implementations, notably the DEC Ada 83 3702implementation, provide many extensions to package @code{System}. 3703 3704For each such implementation accommodated by this pragma, GNAT provides a 3705package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 3706implementation, which provides the required additional definitions. You 3707can use this package in two ways. You can @code{with} it in the normal 3708way and access entities either by selection or using a @code{use} 3709clause. In this case no special processing is required. 3710 3711However, if existing code contains references such as 3712@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended 3713definitions provided in package @code{System}, you may use this pragma 3714to extend visibility in @code{System} in a non-standard way that 3715provides greater compatibility with the existing code. Pragma 3716@code{Extend_System} is a configuration pragma whose single argument is 3717the name of the package containing the extended definition 3718(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3719control of this pragma will be processed using special visibility 3720processing that looks in package @code{System.Aux_@emph{xxx}} where 3721@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in 3722package @code{System}, but not found in package @code{System}. 3723 3724You can use this pragma either to access a predefined @code{System} 3725extension supplied with the compiler, for example @code{Aux_DEC} or 3726you can construct your own extension unit following the above 3727definition. Note that such a package is a child of @code{System} 3728and thus is considered part of the implementation. 3729To compile it you will have to use the @emph{-gnatg} switch 3730for compiling System units, as explained in the 3731GNAT User's Guide. 3732 3733@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3734@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{67} 3735@section Pragma Extensions_Allowed 3736 3737 3738@geindex Ada Extensions 3739 3740@geindex GNAT Extensions 3741 3742Syntax: 3743 3744@example 3745pragma Extensions_Allowed (On | Off); 3746@end example 3747 3748This configuration pragma enables or disables the implementation 3749extension mode (the use of Off as a parameter cancels the effect 3750of the @emph{-gnatX} command switch). 3751 3752In extension mode, the latest version of the Ada language is 3753implemented (currently Ada 2012), and in addition a small number 3754of GNAT specific extensions are recognized as follows: 3755 3756 3757@table @asis 3758 3759@item @emph{Constrained attribute for generic objects} 3760 3761The @code{Constrained} attribute is permitted for objects of 3762generic types. The result indicates if the corresponding actual 3763is constrained. 3764@end table 3765 3766@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3767@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{68}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{69} 3768@section Pragma Extensions_Visible 3769 3770 3771Syntax: 3772 3773@example 3774pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3775@end example 3776 3777For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} 3778in the SPARK 2014 Reference Manual, section 6.1.7. 3779 3780@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3781@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6a} 3782@section Pragma External 3783 3784 3785Syntax: 3786 3787@example 3788pragma External ( 3789 [ Convention =>] convention_IDENTIFIER, 3790 [ Entity =>] LOCAL_NAME 3791 [, [External_Name =>] static_string_EXPRESSION ] 3792 [, [Link_Name =>] static_string_EXPRESSION ]); 3793@end example 3794 3795This pragma is identical in syntax and semantics to pragma 3796@code{Export} as defined in the Ada Reference Manual. It is 3797provided for compatibility with some Ada 83 compilers that 3798used this pragma for exactly the same purposes as pragma 3799@code{Export} before the latter was standardized. 3800 3801@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3802@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6b} 3803@section Pragma External_Name_Casing 3804 3805 3806@geindex Dec Ada 83 casing compatibility 3807 3808@geindex External Names 3809@geindex casing 3810 3811@geindex Casing of External names 3812 3813Syntax: 3814 3815@example 3816pragma External_Name_Casing ( 3817 Uppercase | Lowercase 3818 [, Uppercase | Lowercase | As_Is]); 3819@end example 3820 3821This pragma provides control over the casing of external names associated 3822with Import and Export pragmas. There are two cases to consider: 3823 3824 3825@itemize * 3826 3827@item 3828Implicit external names 3829 3830Implicit external names are derived from identifiers. The most common case 3831arises when a standard Ada Import or Export pragma is used with only two 3832arguments, as in: 3833 3834@example 3835pragma Import (C, C_Routine); 3836@end example 3837 3838Since Ada is a case-insensitive language, the spelling of the identifier in 3839the Ada source program does not provide any information on the desired 3840casing of the external name, and so a convention is needed. In GNAT the 3841default treatment is that such names are converted to all lower case 3842letters. This corresponds to the normal C style in many environments. 3843The first argument of pragma @code{External_Name_Casing} can be used to 3844control this treatment. If @code{Uppercase} is specified, then the name 3845will be forced to all uppercase letters. If @code{Lowercase} is specified, 3846then the normal default of all lower case letters will be used. 3847 3848This same implicit treatment is also used in the case of extended DEC Ada 83 3849compatible Import and Export pragmas where an external name is explicitly 3850specified using an identifier rather than a string. 3851 3852@item 3853Explicit external names 3854 3855Explicit external names are given as string literals. The most common case 3856arises when a standard Ada Import or Export pragma is used with three 3857arguments, as in: 3858 3859@example 3860pragma Import (C, C_Routine, "C_routine"); 3861@end example 3862 3863In this case, the string literal normally provides the exact casing required 3864for the external name. The second argument of pragma 3865@code{External_Name_Casing} may be used to modify this behavior. 3866If @code{Uppercase} is specified, then the name 3867will be forced to all uppercase letters. If @code{Lowercase} is specified, 3868then the name will be forced to all lowercase letters. A specification of 3869@code{As_Is} provides the normal default behavior in which the casing is 3870taken from the string provided. 3871@end itemize 3872 3873This pragma may appear anywhere that a pragma is valid. In particular, it 3874can be used as a configuration pragma in the @code{gnat.adc} file, in which 3875case it applies to all subsequent compilations, or it can be used as a program 3876unit pragma, in which case it only applies to the current unit, or it can 3877be used more locally to control individual Import/Export pragmas. 3878 3879It was primarily intended for use with OpenVMS systems, where many 3880compilers convert all symbols to upper case by default. For interfacing to 3881such compilers (e.g., the DEC C compiler), it may be convenient to use 3882the pragma: 3883 3884@example 3885pragma External_Name_Casing (Uppercase, Uppercase); 3886@end example 3887 3888to enforce the upper casing of all external symbols. 3889 3890@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 3891@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6c} 3892@section Pragma Fast_Math 3893 3894 3895Syntax: 3896 3897@example 3898pragma Fast_Math; 3899@end example 3900 3901This is a configuration pragma which activates a mode in which speed is 3902considered more important for floating-point operations than absolutely 3903accurate adherence to the requirements of the standard. Currently the 3904following operations are affected: 3905 3906 3907@table @asis 3908 3909@item @emph{Complex Multiplication} 3910 3911The normal simple formula for complex multiplication can result in intermediate 3912overflows for numbers near the end of the range. The Ada standard requires that 3913this situation be detected and corrected by scaling, but in Fast_Math mode such 3914cases will simply result in overflow. Note that to take advantage of this you 3915must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 3916under control of the pragma, rather than use the preinstantiated versions. 3917@end table 3918 3919@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 3920@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6d}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6e} 3921@section Pragma Favor_Top_Level 3922 3923 3924Syntax: 3925 3926@example 3927pragma Favor_Top_Level (type_NAME); 3928@end example 3929 3930The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram 3931type. This pragma is an efficiency hint to the compiler, regarding the use of 3932@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. 3933The pragma means that nested subprograms are not used with this type, or are 3934rare, so that the generated code should be efficient in the top-level case. 3935When this pragma is used, dynamically generated trampolines may be used on some 3936targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. 3937 3938@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 3939@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6f} 3940@section Pragma Finalize_Storage_Only 3941 3942 3943Syntax: 3944 3945@example 3946pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3947@end example 3948 3949The argument of pragma @code{Finalize_Storage_Only} must denote a local type which 3950is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The 3951pragma suppresses the call to @code{Finalize} for declared library-level objects 3952of the argument type. This is mostly useful for types where finalization is 3953only used to deal with storage reclamation since in most environments it is 3954not necessary to reclaim memory just before terminating execution, hence the 3955name. Note that this pragma does not suppress Finalize calls for library-level 3956heap-allocated objects (see pragma @code{No_Heap_Finalization}). 3957 3958@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 3959@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{70} 3960@section Pragma Float_Representation 3961 3962 3963Syntax: 3964 3965@example 3966pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3967 3968FLOAT_REP ::= VAX_Float | IEEE_Float 3969@end example 3970 3971In the one argument form, this pragma is a configuration pragma which 3972allows control over the internal representation chosen for the predefined 3973floating point types declared in the packages @code{Standard} and 3974@code{System}. This pragma is only provided for compatibility and has no effect. 3975 3976The two argument form specifies the representation to be used for 3977the specified floating-point type. The argument must 3978be @code{IEEE_Float} to specify the use of IEEE format, as follows: 3979 3980 3981@itemize * 3982 3983@item 3984For a digits value of 6, 32-bit IEEE short format will be used. 3985 3986@item 3987For a digits value of 15, 64-bit IEEE long format will be used. 3988 3989@item 3990No other value of digits is permitted. 3991@end itemize 3992 3993@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 3994@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{72} 3995@section Pragma Ghost 3996 3997 3998Syntax: 3999 4000@example 4001pragma Ghost [ (boolean_EXPRESSION) ]; 4002@end example 4003 4004For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK 40052014 Reference Manual, section 6.9. 4006 4007@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 4008@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{73}@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{74} 4009@section Pragma Global 4010 4011 4012Syntax: 4013 4014@example 4015pragma Global (GLOBAL_SPECIFICATION); 4016 4017GLOBAL_SPECIFICATION ::= 4018 null 4019 | (GLOBAL_LIST) 4020 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 4021 4022MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 4023 4024MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 4025GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 4026GLOBAL_ITEM ::= NAME 4027@end example 4028 4029For the semantics of this pragma, see the entry for aspect @code{Global} in the 4030SPARK 2014 Reference Manual, section 6.1.4. 4031 4032@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 4033@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{75} 4034@section Pragma Ident 4035 4036 4037Syntax: 4038 4039@example 4040pragma Ident (static_string_EXPRESSION); 4041@end example 4042 4043This pragma is identical in effect to pragma @code{Comment}. It is provided 4044for compatibility with other Ada compilers providing this pragma. 4045 4046@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 4047@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{76} 4048@section Pragma Ignore_Pragma 4049 4050 4051Syntax: 4052 4053@example 4054pragma Ignore_Pragma (pragma_IDENTIFIER); 4055@end example 4056 4057This is a configuration pragma 4058that takes a single argument that is a simple identifier. Any subsequent 4059use of a pragma whose pragma identifier matches this argument will be 4060silently ignored. This may be useful when legacy code or code intended 4061for compilation with some other compiler contains pragmas that match the 4062name, but not the exact implementation, of a GNAT pragma. The use of this 4063pragma allows such pragmas to be ignored, which may be useful in CodePeer 4064mode, or during porting of legacy code. 4065 4066@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 4067@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{77} 4068@section Pragma Implementation_Defined 4069 4070 4071Syntax: 4072 4073@example 4074pragma Implementation_Defined (local_NAME); 4075@end example 4076 4077This pragma marks a previously declared entity as implementation-defined. 4078For an overloaded entity, applies to the most recent homonym. 4079 4080@example 4081pragma Implementation_Defined; 4082@end example 4083 4084The form with no arguments appears anywhere within a scope, most 4085typically a package spec, and indicates that all entities that are 4086defined within the package spec are Implementation_Defined. 4087 4088This pragma is used within the GNAT runtime library to identify 4089implementation-defined entities introduced in language-defined units, 4090for the purpose of implementing the No_Implementation_Identifiers 4091restriction. 4092 4093@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 4094@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{78} 4095@section Pragma Implemented 4096 4097 4098Syntax: 4099 4100@example 4101pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 4102 4103implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 4104@end example 4105 4106This is an Ada 2012 representation pragma which applies to protected, task 4107and synchronized interface primitives. The use of pragma Implemented provides 4108a way to impose a static requirement on the overriding operation by adhering 4109to one of the three implementation kinds: entry, protected procedure or any of 4110the above. This pragma is available in all earlier versions of Ada as an 4111implementation-defined pragma. 4112 4113@example 4114type Synch_Iface is synchronized interface; 4115procedure Prim_Op (Obj : in out Iface) is abstract; 4116pragma Implemented (Prim_Op, By_Protected_Procedure); 4117 4118protected type Prot_1 is new Synch_Iface with 4119 procedure Prim_Op; -- Legal 4120end Prot_1; 4121 4122protected type Prot_2 is new Synch_Iface with 4123 entry Prim_Op; -- Illegal 4124end Prot_2; 4125 4126task type Task_Typ is new Synch_Iface with 4127 entry Prim_Op; -- Illegal 4128end Task_Typ; 4129@end example 4130 4131When applied to the procedure_or_entry_NAME of a requeue statement, pragma 4132Implemented determines the runtime behavior of the requeue. Implementation kind 4133By_Entry guarantees that the action of requeueing will proceed from an entry to 4134another entry. Implementation kind By_Protected_Procedure transforms the 4135requeue into a dispatching call, thus eliminating the chance of blocking. Kind 4136By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 4137the target's overriding subprogram kind. 4138 4139@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 4140@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{79} 4141@section Pragma Implicit_Packing 4142 4143 4144@geindex Rational Profile 4145 4146Syntax: 4147 4148@example 4149pragma Implicit_Packing; 4150@end example 4151 4152This is a configuration pragma that requests implicit packing for packed 4153arrays for which a size clause is given but no explicit pragma Pack or 4154specification of Component_Size is present. It also applies to records 4155where no record representation clause is present. Consider this example: 4156 4157@example 4158type R is array (0 .. 7) of Boolean; 4159for R'Size use 8; 4160@end example 4161 4162In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 4163does not change the layout of a composite object. So the Size clause in the 4164above example is normally rejected, since the default layout of the array uses 41658-bit components, and thus the array requires a minimum of 64 bits. 4166 4167If this declaration is compiled in a region of code covered by an occurrence 4168of the configuration pragma Implicit_Packing, then the Size clause in this 4169and similar examples will cause implicit packing and thus be accepted. For 4170this implicit packing to occur, the type in question must be an array of small 4171components whose size is known at compile time, and the Size clause must 4172specify the exact size that corresponds to the number of elements in the array 4173multiplied by the size in bits of the component type (both single and 4174multi-dimensioned arrays can be controlled with this pragma). 4175 4176@geindex Array packing 4177 4178Similarly, the following example shows the use in the record case 4179 4180@example 4181type r is record 4182 a, b, c, d, e, f, g, h : boolean; 4183 chr : character; 4184end record; 4185for r'size use 16; 4186@end example 4187 4188Without a pragma Pack, each Boolean field requires 8 bits, so the 4189minimum size is 72 bits, but with a pragma Pack, 16 bits would be 4190sufficient. The use of pragma Implicit_Packing allows this record 4191declaration to compile without an explicit pragma Pack. 4192 4193@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 4194@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7a} 4195@section Pragma Import_Function 4196 4197 4198Syntax: 4199 4200@example 4201pragma Import_Function ( 4202 [Internal =>] LOCAL_NAME, 4203 [, [External =>] EXTERNAL_SYMBOL] 4204 [, [Parameter_Types =>] PARAMETER_TYPES] 4205 [, [Result_Type =>] SUBTYPE_MARK] 4206 [, [Mechanism =>] MECHANISM] 4207 [, [Result_Mechanism =>] MECHANISM_NAME]); 4208 4209EXTERNAL_SYMBOL ::= 4210 IDENTIFIER 4211| static_string_EXPRESSION 4212 4213PARAMETER_TYPES ::= 4214 null 4215| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4216 4217TYPE_DESIGNATOR ::= 4218 subtype_NAME 4219| subtype_Name ' Access 4220 4221MECHANISM ::= 4222 MECHANISM_NAME 4223| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4224 4225MECHANISM_ASSOCIATION ::= 4226 [formal_parameter_NAME =>] MECHANISM_NAME 4227 4228MECHANISM_NAME ::= 4229 Value 4230| Reference 4231@end example 4232 4233This pragma is used in conjunction with a pragma @code{Import} to 4234specify additional information for an imported function. The pragma 4235@code{Import} (or equivalent pragma @code{Interface}) must precede the 4236@code{Import_Function} pragma and both must appear in the same 4237declarative part as the function specification. 4238 4239The @code{Internal} argument must uniquely designate 4240the function to which the 4241pragma applies. If more than one function name exists of this name in 4242the declarative part you must use the @code{Parameter_Types} and 4243@code{Result_Type} parameters to achieve the required unique 4244designation. Subtype marks in these parameters must exactly match the 4245subtypes in the corresponding function specification, using positional 4246notation to match parameters with subtype marks. 4247The form with an @code{'Access} attribute can be used to match an 4248anonymous access parameter. 4249 4250You may optionally use the @code{Mechanism} and @code{Result_Mechanism} 4251parameters to specify passing mechanisms for the 4252parameters and result. If you specify a single mechanism name, it 4253applies to all parameters. Otherwise you may specify a mechanism on a 4254parameter by parameter basis using either positional or named 4255notation. If the mechanism is not specified, the default mechanism 4256is used. 4257 4258@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 4259@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7b} 4260@section Pragma Import_Object 4261 4262 4263Syntax: 4264 4265@example 4266pragma Import_Object 4267 [Internal =>] LOCAL_NAME 4268 [, [External =>] EXTERNAL_SYMBOL] 4269 [, [Size =>] EXTERNAL_SYMBOL]); 4270 4271EXTERNAL_SYMBOL ::= 4272 IDENTIFIER 4273| static_string_EXPRESSION 4274@end example 4275 4276This pragma designates an object as imported, and apart from the 4277extended rules for external symbols, is identical in effect to the use of 4278the normal @code{Import} pragma applied to an object. Unlike the 4279subprogram case, you need not use a separate @code{Import} pragma, 4280although you may do so (and probably should do so from a portability 4281point of view). @code{size} is syntax checked, but otherwise ignored by 4282GNAT. 4283 4284@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 4285@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7c} 4286@section Pragma Import_Procedure 4287 4288 4289Syntax: 4290 4291@example 4292pragma Import_Procedure ( 4293 [Internal =>] LOCAL_NAME 4294 [, [External =>] EXTERNAL_SYMBOL] 4295 [, [Parameter_Types =>] PARAMETER_TYPES] 4296 [, [Mechanism =>] MECHANISM]); 4297 4298EXTERNAL_SYMBOL ::= 4299 IDENTIFIER 4300| static_string_EXPRESSION 4301 4302PARAMETER_TYPES ::= 4303 null 4304| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4305 4306TYPE_DESIGNATOR ::= 4307 subtype_NAME 4308| subtype_Name ' Access 4309 4310MECHANISM ::= 4311 MECHANISM_NAME 4312| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4313 4314MECHANISM_ASSOCIATION ::= 4315 [formal_parameter_NAME =>] MECHANISM_NAME 4316 4317MECHANISM_NAME ::= Value | Reference 4318@end example 4319 4320This pragma is identical to @code{Import_Function} except that it 4321applies to a procedure rather than a function and the parameters 4322@code{Result_Type} and @code{Result_Mechanism} are not permitted. 4323 4324@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4325@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7d} 4326@section Pragma Import_Valued_Procedure 4327 4328 4329Syntax: 4330 4331@example 4332pragma Import_Valued_Procedure ( 4333 [Internal =>] LOCAL_NAME 4334 [, [External =>] EXTERNAL_SYMBOL] 4335 [, [Parameter_Types =>] PARAMETER_TYPES] 4336 [, [Mechanism =>] MECHANISM]); 4337 4338EXTERNAL_SYMBOL ::= 4339 IDENTIFIER 4340| static_string_EXPRESSION 4341 4342PARAMETER_TYPES ::= 4343 null 4344| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4345 4346TYPE_DESIGNATOR ::= 4347 subtype_NAME 4348| subtype_Name ' Access 4349 4350MECHANISM ::= 4351 MECHANISM_NAME 4352| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4353 4354MECHANISM_ASSOCIATION ::= 4355 [formal_parameter_NAME =>] MECHANISM_NAME 4356 4357MECHANISM_NAME ::= Value | Reference 4358@end example 4359 4360This pragma is identical to @code{Import_Procedure} except that the 4361first parameter of @code{LOCAL_NAME}, which must be present, must be of 4362mode @code{out}, and externally the subprogram is treated as a function 4363with this parameter as the result of the function. The purpose of this 4364capability is to allow the use of @code{out} and @code{in out} 4365parameters in interfacing to external functions (which are not permitted 4366in Ada functions). You may optionally use the @code{Mechanism} 4367parameters to specify passing mechanisms for the parameters. 4368If you specify a single mechanism name, it applies to all parameters. 4369Otherwise you may specify a mechanism on a parameter by parameter 4370basis using either positional or named notation. If the mechanism is not 4371specified, the default mechanism is used. 4372 4373Note that it is important to use this pragma in conjunction with a separate 4374pragma Import that specifies the desired convention, since otherwise the 4375default convention is Ada, which is almost certainly not what is required. 4376 4377@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4378@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7e} 4379@section Pragma Independent 4380 4381 4382Syntax: 4383 4384@example 4385pragma Independent (Local_NAME); 4386@end example 4387 4388This pragma is standard in Ada 2012 mode (which also provides an aspect 4389of the same name). It is also available as an implementation-defined 4390pragma in all earlier versions. It specifies that the 4391designated object or all objects of the designated type must be 4392independently addressable. This means that separate tasks can safely 4393manipulate such objects. For example, if two components of a record are 4394independent, then two separate tasks may access these two components. 4395This may place 4396constraints on the representation of the object (for instance prohibiting 4397tight packing). 4398 4399@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4400@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7f} 4401@section Pragma Independent_Components 4402 4403 4404Syntax: 4405 4406@example 4407pragma Independent_Components (Local_NAME); 4408@end example 4409 4410This pragma is standard in Ada 2012 mode (which also provides an aspect 4411of the same name). It is also available as an implementation-defined 4412pragma in all earlier versions. It specifies that the components of the 4413designated object, or the components of each object of the designated 4414type, must be 4415independently addressable. This means that separate tasks can safely 4416manipulate separate components in the composite object. This may place 4417constraints on the representation of the object (for instance prohibiting 4418tight packing). 4419 4420@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4421@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{81} 4422@section Pragma Initial_Condition 4423 4424 4425Syntax: 4426 4427@example 4428pragma Initial_Condition (boolean_EXPRESSION); 4429@end example 4430 4431For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} 4432in the SPARK 2014 Reference Manual, section 7.1.6. 4433 4434@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4435@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{82} 4436@section Pragma Initialize_Scalars 4437 4438 4439@geindex debugging with Initialize_Scalars 4440 4441Syntax: 4442 4443@example 4444pragma Initialize_Scalars; 4445@end example 4446 4447This pragma is similar to @code{Normalize_Scalars} conceptually but has 4448two important differences. First, there is no requirement for the pragma 4449to be used uniformly in all units of a partition, in particular, it is fine 4450to use this just for some or all of the application units of a partition, 4451without needing to recompile the run-time library. 4452 4453In the case where some units are compiled with the pragma, and some without, 4454then a declaration of a variable where the type is defined in package 4455Standard or is locally declared will always be subject to initialization, 4456as will any declaration of a scalar variable. For composite variables, 4457whether the variable is initialized may also depend on whether the package 4458in which the type of the variable is declared is compiled with the pragma. 4459 4460The other important difference is that you can control the value used 4461for initializing scalar objects. At bind time, you can select several 4462options for initialization. You can 4463initialize with invalid values (similar to Normalize_Scalars, though for 4464Initialize_Scalars it is not always possible to determine the invalid 4465values in complex cases like signed component fields with non-standard 4466sizes). You can also initialize with high or 4467low values, or with a specified bit pattern. See the GNAT 4468User's Guide for binder options for specifying these cases. 4469 4470This means that you can compile a program, and then without having to 4471recompile the program, you can run it with different values being used 4472for initializing otherwise uninitialized values, to test if your program 4473behavior depends on the choice. Of course the behavior should not change, 4474and if it does, then most likely you have an incorrect reference to an 4475uninitialized value. 4476 4477It is even possible to change the value at execution time eliminating even 4478the need to rebind with a different switch using an environment variable. 4479See the GNAT User's Guide for details. 4480 4481Note that pragma @code{Initialize_Scalars} is particularly useful in 4482conjunction with the enhanced validity checking that is now provided 4483in GNAT, which checks for invalid values under more conditions. 4484Using this feature (see description of the @emph{-gnatV} flag in the 4485GNAT User's Guide) in conjunction with 4486pragma @code{Initialize_Scalars} 4487provides a powerful new tool to assist in the detection of problems 4488caused by uninitialized variables. 4489 4490Note: the use of @code{Initialize_Scalars} has a fairly extensive 4491effect on the generated code. This may cause your code to be 4492substantially larger. It may also cause an increase in the amount 4493of stack required, so it is probably a good idea to turn on stack 4494checking (see description of stack checking in the GNAT 4495User's Guide) when using this pragma. 4496 4497@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4498@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{84} 4499@section Pragma Initializes 4500 4501 4502Syntax: 4503 4504@example 4505pragma Initializes (INITIALIZATION_LIST); 4506 4507INITIALIZATION_LIST ::= 4508 null 4509 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4510 4511INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4512 4513INPUT_LIST ::= 4514 null 4515 | INPUT 4516 | (INPUT @{, INPUT@}) 4517 4518INPUT ::= name 4519@end example 4520 4521For the semantics of this pragma, see the entry for aspect @code{Initializes} in the 4522SPARK 2014 Reference Manual, section 7.1.5. 4523 4524@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4525@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{85}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{86} 4526@section Pragma Inline_Always 4527 4528 4529Syntax: 4530 4531@example 4532pragma Inline_Always (NAME [, NAME]); 4533@end example 4534 4535Similar to pragma @code{Inline} except that inlining is unconditional. 4536Inline_Always instructs the compiler to inline every direct call to the 4537subprogram or else to emit a compilation error, independently of any 4538option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. 4539It is an error to take the address or access of @code{NAME}. It is also an error to 4540apply this pragma to a primitive operation of a tagged type. Thanks to such 4541restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. 4542 4543@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4544@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{87} 4545@section Pragma Inline_Generic 4546 4547 4548Syntax: 4549 4550@example 4551pragma Inline_Generic (GNAME @{, GNAME@}); 4552 4553GNAME ::= generic_unit_NAME | generic_instance_NAME 4554@end example 4555 4556This pragma is provided for compatibility with Dec Ada 83. It has 4557no effect in GNAT (which always inlines generics), other 4558than to check that the given names are all names of generic units or 4559generic instances. 4560 4561@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4562@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{88} 4563@section Pragma Interface 4564 4565 4566Syntax: 4567 4568@example 4569pragma Interface ( 4570 [Convention =>] convention_identifier, 4571 [Entity =>] local_NAME 4572 [, [External_Name =>] static_string_expression] 4573 [, [Link_Name =>] static_string_expression]); 4574@end example 4575 4576This pragma is identical in syntax and semantics to 4577the standard Ada pragma @code{Import}. It is provided for compatibility 4578with Ada 83. The definition is upwards compatible both with pragma 4579@code{Interface} as defined in the Ada 83 Reference Manual, and also 4580with some extended implementations of this pragma in certain Ada 83 4581implementations. The only difference between pragma @code{Interface} 4582and pragma @code{Import} is that there is special circuitry to allow 4583both pragmas to appear for the same subprogram entity (normally it 4584is illegal to have multiple @code{Import} pragmas. This is useful in 4585maintaining Ada 83/Ada 95 compatibility and is compatible with other 4586Ada 83 compilers. 4587 4588@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4589@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{89} 4590@section Pragma Interface_Name 4591 4592 4593Syntax: 4594 4595@example 4596pragma Interface_Name ( 4597 [Entity =>] LOCAL_NAME 4598 [, [External_Name =>] static_string_EXPRESSION] 4599 [, [Link_Name =>] static_string_EXPRESSION]); 4600@end example 4601 4602This pragma provides an alternative way of specifying the interface name 4603for an interfaced subprogram, and is provided for compatibility with Ada 460483 compilers that use the pragma for this purpose. You must provide at 4605least one of @code{External_Name} or @code{Link_Name}. 4606 4607@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4608@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8a} 4609@section Pragma Interrupt_Handler 4610 4611 4612Syntax: 4613 4614@example 4615pragma Interrupt_Handler (procedure_LOCAL_NAME); 4616@end example 4617 4618This program unit pragma is supported for parameterless protected procedures 4619as described in Annex C of the Ada Reference Manual. On the AAMP target 4620the pragma can also be specified for nonprotected parameterless procedures 4621that are declared at the library level (which includes procedures 4622declared at the top level of a library package). In the case of AAMP, 4623when this pragma is applied to a nonprotected procedure, the instruction 4624@code{IERET} is generated for returns from the procedure, enabling 4625maskable interrupts, in place of the normal return instruction. 4626 4627@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4628@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8b} 4629@section Pragma Interrupt_State 4630 4631 4632Syntax: 4633 4634@example 4635pragma Interrupt_State 4636 ([Name =>] value, 4637 [State =>] SYSTEM | RUNTIME | USER); 4638@end example 4639 4640Normally certain interrupts are reserved to the implementation. Any attempt 4641to attach an interrupt causes Program_Error to be raised, as described in 4642RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 4643many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4644reserved to the implementation, so that @code{Ctrl-C} can be used to 4645interrupt execution. Additionally, signals such as @code{SIGSEGV}, 4646@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 4647Ada exceptions, or used to implement run-time functions such as the 4648@code{abort} statement and stack overflow checking. 4649 4650Pragma @code{Interrupt_State} provides a general mechanism for overriding 4651such uses of interrupts. It subsumes the functionality of pragma 4652@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 4653available on Windows or VMS. On all other platforms than VxWorks, 4654it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4655and may be used to mark interrupts required by the board support package 4656as reserved. 4657 4658Interrupts can be in one of three states: 4659 4660 4661@itemize * 4662 4663@item 4664System 4665 4666The interrupt is reserved (no Ada handler can be installed), and the 4667Ada run-time may not install a handler. As a result you are guaranteed 4668standard system default action if this interrupt is raised. This also allows 4669installing a low level handler via C APIs such as sigaction(), outside 4670of Ada control. 4671 4672@item 4673Runtime 4674 4675The interrupt is reserved (no Ada handler can be installed). The run time 4676is allowed to install a handler for internal control purposes, but is 4677not required to do so. 4678 4679@item 4680User 4681 4682The interrupt is unreserved. The user may install an Ada handler via 4683Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 4684some other action. 4685@end itemize 4686 4687These states are the allowed values of the @code{State} parameter of the 4688pragma. The @code{Name} parameter is a value of the type 4689@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4690@code{Ada.Interrupts.Names}. 4691 4692This is a configuration pragma, and the binder will check that there 4693are no inconsistencies between different units in a partition in how a 4694given interrupt is specified. It may appear anywhere a pragma is legal. 4695 4696The effect is to move the interrupt to the specified state. 4697 4698By declaring interrupts to be SYSTEM, you guarantee the standard system 4699action, such as a core dump. 4700 4701By declaring interrupts to be USER, you guarantee that you can install 4702a handler. 4703 4704Note that certain signals on many operating systems cannot be caught and 4705handled by applications. In such cases, the pragma is ignored. See the 4706operating system documentation, or the value of the array @code{Reserved} 4707declared in the spec of package @code{System.OS_Interface}. 4708 4709Overriding the default state of signals used by the Ada runtime may interfere 4710with an application's runtime behavior in the cases of the synchronous signals, 4711and in the case of the signal used to implement the @code{abort} statement. 4712 4713@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4714@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8c}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8d} 4715@section Pragma Invariant 4716 4717 4718Syntax: 4719 4720@example 4721pragma Invariant 4722 ([Entity =>] private_type_LOCAL_NAME, 4723 [Check =>] EXPRESSION 4724 [,[Message =>] String_Expression]); 4725@end example 4726 4727This pragma provides exactly the same capabilities as the Type_Invariant aspect 4728defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4729Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4730requires the use of the aspect syntax, which is not available except in 2012 4731mode, it is not possible to use the Type_Invariant aspect in earlier versions 4732of Ada. However the Invariant pragma may be used in any version of Ada. Also 4733note that the aspect Invariant is a synonym in GNAT for the aspect 4734Type_Invariant, but there is no pragma Type_Invariant. 4735 4736The pragma must appear within the visible part of the package specification, 4737after the type to which its Entity argument appears. As with the Invariant 4738aspect, the Check expression is not analyzed until the end of the visible 4739part of the package, so it may contain forward references. The Message 4740argument, if present, provides the exception message used if the invariant 4741is violated. If no Message parameter is provided, a default message that 4742identifies the line on which the pragma appears is used. 4743 4744It is permissible to have multiple Invariants for the same type entity, in 4745which case they are and'ed together. It is permissible to use this pragma 4746in Ada 2012 mode, but you cannot have both an invariant aspect and an 4747invariant pragma for the same entity. 4748 4749For further details on the use of this pragma, see the Ada 2012 documentation 4750of the Type_Invariant aspect. 4751 4752@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4753@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8e} 4754@section Pragma Keep_Names 4755 4756 4757Syntax: 4758 4759@example 4760pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4761@end example 4762 4763The @code{LOCAL_NAME} argument 4764must refer to an enumeration first subtype 4765in the current declarative part. The effect is to retain the enumeration 4766literal names for use by @code{Image} and @code{Value} even if a global 4767@code{Discard_Names} pragma applies. This is useful when you want to 4768generally suppress enumeration literal names and for example you therefore 4769use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you 4770want to retain the names for specific enumeration types. 4771 4772@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4773@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8f} 4774@section Pragma License 4775 4776 4777@geindex License checking 4778 4779Syntax: 4780 4781@example 4782pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4783@end example 4784 4785This pragma is provided to allow automated checking for appropriate license 4786conditions with respect to the standard and modified GPL. A pragma 4787@code{License}, which is a configuration pragma that typically appears at 4788the start of a source file or in a separate @code{gnat.adc} file, specifies 4789the licensing conditions of a unit as follows: 4790 4791 4792@itemize * 4793 4794@item 4795Unrestricted 4796This is used for a unit that can be freely used with no license restrictions. 4797Examples of such units are public domain units, and units from the Ada 4798Reference Manual. 4799 4800@item 4801GPL 4802This is used for a unit that is licensed under the unmodified GPL, and which 4803therefore cannot be @code{with}ed by a restricted unit. 4804 4805@item 4806Modified_GPL 4807This is used for a unit licensed under the GNAT modified GPL that includes 4808a special exception paragraph that specifically permits the inclusion of 4809the unit in programs without requiring the entire program to be released 4810under the GPL. 4811 4812@item 4813Restricted 4814This is used for a unit that is restricted in that it is not permitted to 4815depend on units that are licensed under the GPL. Typical examples are 4816proprietary code that is to be released under more restrictive license 4817conditions. Note that restricted units are permitted to @code{with} units 4818which are licensed under the modified GPL (this is the whole point of the 4819modified GPL). 4820@end itemize 4821 4822Normally a unit with no @code{License} pragma is considered to have an 4823unknown license, and no checking is done. However, standard GNAT headers 4824are recognized, and license information is derived from them as follows. 4825 4826A GNAT license header starts with a line containing 78 hyphens. The following 4827comment text is searched for the appearance of any of the following strings. 4828 4829If the string 'GNU General Public License' is found, then the unit is assumed 4830to have GPL license, unless the string 'As a special exception' follows, in 4831which case the license is assumed to be modified GPL. 4832 4833If one of the strings 4834'This specification is adapted from the Ada Semantic Interface' or 4835'This specification is derived from the Ada Reference Manual' is found 4836then the unit is assumed to be unrestricted. 4837 4838These default actions means that a program with a restricted license pragma 4839will automatically get warnings if a GPL unit is inappropriately 4840@code{with}ed. For example, the program: 4841 4842@example 4843with Sem_Ch3; 4844with GNAT.Sockets; 4845procedure Secret_Stuff is 4846 ... 4847end Secret_Stuff 4848@end example 4849 4850if compiled with pragma @code{License} (@code{Restricted}) in a 4851@code{gnat.adc} file will generate the warning: 4852 4853@example 48541. with Sem_Ch3; 4855 | 4856 >>> license of withed unit "Sem_Ch3" is incompatible 4857 48582. with GNAT.Sockets; 48593. procedure Secret_Stuff is 4860@end example 4861 4862Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 4863compiler and is licensed under the 4864GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 4865run time, and is therefore licensed under the modified GPL. 4866 4867@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 4868@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{90} 4869@section Pragma Link_With 4870 4871 4872Syntax: 4873 4874@example 4875pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4876@end example 4877 4878This pragma is provided for compatibility with certain Ada 83 compilers. 4879It has exactly the same effect as pragma @code{Linker_Options} except 4880that spaces occurring within one of the string expressions are treated 4881as separators. For example, in the following case: 4882 4883@example 4884pragma Link_With ("-labc -ldef"); 4885@end example 4886 4887results in passing the strings @code{-labc} and @code{-ldef} as two 4888separate arguments to the linker. In addition pragma Link_With allows 4889multiple arguments, with the same effect as successive pragmas. 4890 4891@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 4892@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{91} 4893@section Pragma Linker_Alias 4894 4895 4896Syntax: 4897 4898@example 4899pragma Linker_Alias ( 4900 [Entity =>] LOCAL_NAME, 4901 [Target =>] static_string_EXPRESSION); 4902@end example 4903 4904@code{LOCAL_NAME} must refer to an object that is declared at the library 4905level. This pragma establishes the given entity as a linker alias for the 4906given target. It is equivalent to @code{__attribute__((alias))} in GNU C 4907and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol 4908@code{static_string_EXPRESSION} in the object file, that is to say no space 4909is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved 4910to the same address as @code{static_string_EXPRESSION} by the linker. 4911 4912The actual linker name for the target must be used (e.g., the fully 4913encoded name with qualification in Ada, or the mangled name in C++), 4914or it must be declared using the C convention with @code{pragma Import} 4915or @code{pragma Export}. 4916 4917Not all target machines support this pragma. On some of them it is accepted 4918only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. 4919 4920@example 4921-- Example of the use of pragma Linker_Alias 4922 4923package p is 4924 i : Integer := 1; 4925 pragma Export (C, i); 4926 4927 new_name_for_i : Integer; 4928 pragma Linker_Alias (new_name_for_i, "i"); 4929end p; 4930@end example 4931 4932@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 4933@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{92} 4934@section Pragma Linker_Constructor 4935 4936 4937Syntax: 4938 4939@example 4940pragma Linker_Constructor (procedure_LOCAL_NAME); 4941@end example 4942 4943@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4944is declared at the library level. A procedure to which this pragma is 4945applied will be treated as an initialization routine by the linker. 4946It is equivalent to @code{__attribute__((constructor))} in GNU C and 4947causes @code{procedure_LOCAL_NAME} to be invoked before the entry point 4948of the executable is called (or immediately after the shared library is 4949loaded if the procedure is linked in a shared library), in particular 4950before the Ada run-time environment is set up. 4951 4952Because of these specific contexts, the set of operations such a procedure 4953can perform is very limited and the type of objects it can manipulate is 4954essentially restricted to the elementary types. In particular, it must only 4955contain code to which pragma Restrictions (No_Elaboration_Code) applies. 4956 4957This pragma is used by GNAT to implement auto-initialization of shared Stand 4958Alone Libraries, which provides a related capability without the restrictions 4959listed above. Where possible, the use of Stand Alone Libraries is preferable 4960to the use of this pragma. 4961 4962@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 4963@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{93} 4964@section Pragma Linker_Destructor 4965 4966 4967Syntax: 4968 4969@example 4970pragma Linker_Destructor (procedure_LOCAL_NAME); 4971@end example 4972 4973@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4974is declared at the library level. A procedure to which this pragma is 4975applied will be treated as a finalization routine by the linker. 4976It is equivalent to @code{__attribute__((destructor))} in GNU C and 4977causes @code{procedure_LOCAL_NAME} to be invoked after the entry point 4978of the executable has exited (or immediately before the shared library 4979is unloaded if the procedure is linked in a shared library), in particular 4980after the Ada run-time environment is shut down. 4981 4982See @code{pragma Linker_Constructor} for the set of restrictions that apply 4983because of these specific contexts. 4984 4985@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 4986@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{95} 4987@section Pragma Linker_Section 4988 4989 4990Syntax: 4991 4992@example 4993pragma Linker_Section ( 4994 [Entity =>] LOCAL_NAME, 4995 [Section =>] static_string_EXPRESSION); 4996@end example 4997 4998@code{LOCAL_NAME} must refer to an object, type, or subprogram that is 4999declared at the library level. This pragma specifies the name of the 5000linker section for the given entity. It is equivalent to 5001@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to 5002be placed in the @code{static_string_EXPRESSION} section of the 5003executable (assuming the linker doesn't rename the section). 5004GNAT also provides an implementation defined aspect of the same name. 5005 5006In the case of specifying this aspect for a type, the effect is to 5007specify the corresponding section for all library-level objects of 5008the type that do not have an explicit linker section set. Note that 5009this only applies to whole objects, not to components of composite objects. 5010 5011In the case of a subprogram, the linker section applies to all previously 5012declared matching overloaded subprograms in the current declarative part 5013which do not already have a linker section assigned. The linker section 5014aspect is useful in this case for specifying different linker sections 5015for different elements of such an overloaded set. 5016 5017Note that an empty string specifies that no linker section is specified. 5018This is not quite the same as omitting the pragma or aspect, since it 5019can be used to specify that one element of an overloaded set of subprograms 5020has the default linker section, or that one object of a type for which a 5021linker section is specified should has the default linker section. 5022 5023The compiler normally places library-level entities in standard sections 5024depending on the class: procedures and functions generally go in the 5025@code{.text} section, initialized variables in the @code{.data} section 5026and uninitialized variables in the @code{.bss} section. 5027 5028Other, special sections may exist on given target machines to map special 5029hardware, for example I/O ports or flash memory. This pragma is a means to 5030defer the final layout of the executable to the linker, thus fully working 5031at the symbolic level with the compiler. 5032 5033Some file formats do not support arbitrary sections so not all target 5034machines support this pragma. The use of this pragma may cause a program 5035execution to be erroneous if it is used to place an entity into an 5036inappropriate section (e.g., a modified variable into the @code{.text} 5037section). See also @code{pragma Persistent_BSS}. 5038 5039@example 5040-- Example of the use of pragma Linker_Section 5041 5042package IO_Card is 5043 Port_A : Integer; 5044 pragma Volatile (Port_A); 5045 pragma Linker_Section (Port_A, ".bss.port_a"); 5046 5047 Port_B : Integer; 5048 pragma Volatile (Port_B); 5049 pragma Linker_Section (Port_B, ".bss.port_b"); 5050 5051 type Port_Type is new Integer with Linker_Section => ".bss"; 5052 PA : Port_Type with Linker_Section => ".bss.PA"; 5053 PB : Port_Type; -- ends up in linker section ".bss" 5054 5055 procedure Q with Linker_Section => "Qsection"; 5056end IO_Card; 5057@end example 5058 5059@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 5060@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{96}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{97} 5061@section Pragma Lock_Free 5062 5063 5064Syntax: 5065This pragma may be specified for protected types or objects. It specifies that 5066the implementation of protected operations must be implemented without locks. 5067Compilation fails if the compiler cannot generate lock-free code for the 5068operations. 5069 5070@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 5071@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{98} 5072@section Pragma Loop_Invariant 5073 5074 5075Syntax: 5076 5077@example 5078pragma Loop_Invariant ( boolean_EXPRESSION ); 5079@end example 5080 5081The effect of this pragma is similar to that of pragma @code{Assert}, 5082except that in an @code{Assertion_Policy} pragma, the identifier 5083@code{Loop_Invariant} is used to control whether it is ignored or checked 5084(or disabled). 5085 5086@code{Loop_Invariant} can only appear as one of the items in the sequence 5087of statements of a loop body, or nested inside block statements that 5088appear in the sequence of statements of a loop body. 5089The intention is that it be used to 5090represent a "loop invariant" assertion, i.e. something that is true each 5091time through the loop, and which can be used to show that the loop is 5092achieving its purpose. 5093 5094Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5095apply to the same loop should be grouped in the same sequence of 5096statements. 5097 5098To aid in writing such invariants, the special attribute @code{Loop_Entry} 5099may be used to refer to the value of an expression on entry to the loop. This 5100attribute can only be used within the expression of a @code{Loop_Invariant} 5101pragma. For full details, see documentation of attribute @code{Loop_Entry}. 5102 5103@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 5104@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{99} 5105@section Pragma Loop_Optimize 5106 5107 5108Syntax: 5109 5110@example 5111pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 5112 5113OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 5114@end example 5115 5116This pragma must appear immediately within a loop statement. It allows the 5117programmer to specify optimization hints for the enclosing loop. The hints 5118are not mutually exclusive and can be freely mixed, but not all combinations 5119will yield a sensible outcome. 5120 5121There are five supported optimization hints for a loop: 5122 5123 5124@itemize * 5125 5126@item 5127Ivdep 5128 5129The programmer asserts that there are no loop-carried dependencies 5130which would prevent consecutive iterations of the loop from being 5131executed simultaneously. 5132 5133@item 5134No_Unroll 5135 5136The loop must not be unrolled. This is a strong hint: the compiler will not 5137unroll a loop marked with this hint. 5138 5139@item 5140Unroll 5141 5142The loop should be unrolled. This is a weak hint: the compiler will try to 5143apply unrolling to this loop preferably to other optimizations, notably 5144vectorization, but there is no guarantee that the loop will be unrolled. 5145 5146@item 5147No_Vector 5148 5149The loop must not be vectorized. This is a strong hint: the compiler will not 5150vectorize a loop marked with this hint. 5151 5152@item 5153Vector 5154 5155The loop should be vectorized. This is a weak hint: the compiler will try to 5156apply vectorization to this loop preferably to other optimizations, notably 5157unrolling, but there is no guarantee that the loop will be vectorized. 5158@end itemize 5159 5160These hints do not remove the need to pass the appropriate switches to the 5161compiler in order to enable the relevant optimizations, that is to say 5162@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 5163vectorization. 5164 5165@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 5166@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9a} 5167@section Pragma Loop_Variant 5168 5169 5170Syntax: 5171 5172@example 5173pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 5174LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 5175CHANGE_DIRECTION ::= Increases | Decreases 5176@end example 5177 5178@code{Loop_Variant} can only appear as one of the items in the sequence 5179of statements of a loop body, or nested inside block statements that 5180appear in the sequence of statements of a loop body. 5181It allows the specification of quantities which must always 5182decrease or increase in successive iterations of the loop. In its simplest 5183form, just one expression is specified, whose value must increase or decrease 5184on each iteration of the loop. 5185 5186In a more complex form, multiple arguments can be given which are intepreted 5187in a nesting lexicographic manner. For example: 5188 5189@example 5190pragma Loop_Variant (Increases => X, Decreases => Y); 5191@end example 5192 5193specifies that each time through the loop either X increases, or X stays 5194the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 5195loop is making progress. It can be useful in helping to show informally 5196or prove formally that the loop always terminates. 5197 5198@code{Loop_Variant} is an assertion whose effect can be controlled using 5199an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 5200policy can be @code{Check} to enable the loop variant check, @code{Ignore} 5201to ignore the check (in which case the pragma has no effect on the program), 5202or @code{Disable} in which case the pragma is not even checked for correct 5203syntax. 5204 5205Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5206apply to the same loop should be grouped in the same sequence of 5207statements. 5208 5209The @code{Loop_Entry} attribute may be used within the expressions of the 5210@code{Loop_Variant} pragma to refer to values on entry to the loop. 5211 5212@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 5213@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9b} 5214@section Pragma Machine_Attribute 5215 5216 5217Syntax: 5218 5219@example 5220pragma Machine_Attribute ( 5221 [Entity =>] LOCAL_NAME, 5222 [Attribute_Name =>] static_string_EXPRESSION 5223 [, [Info =>] static_EXPRESSION] ); 5224@end example 5225 5226Machine-dependent attributes can be specified for types and/or 5227declarations. This pragma is semantically equivalent to 5228@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not 5229specified) or @code{__attribute__((@emph{attribute_name(info})))} 5230in GNU C, where @emph{attribute_name} is recognized by the 5231compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine 5232specific macro. A string literal for the optional parameter @code{info} 5233is transformed into an identifier, which may make this pragma unusable 5234for some attributes. 5235For further information see @cite{GNU Compiler Collection (GCC) Internals}. 5236 5237@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 5238@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9c} 5239@section Pragma Main 5240 5241 5242Syntax: 5243 5244@example 5245pragma Main 5246 (MAIN_OPTION [, MAIN_OPTION]); 5247 5248MAIN_OPTION ::= 5249 [Stack_Size =>] static_integer_EXPRESSION 5250| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 5251| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 5252@end example 5253 5254This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5255no effect in GNAT, other than being syntax checked. 5256 5257@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas 5258@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9d} 5259@section Pragma Main_Storage 5260 5261 5262Syntax: 5263 5264@example 5265pragma Main_Storage 5266 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 5267 5268MAIN_STORAGE_OPTION ::= 5269 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 5270| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 5271@end example 5272 5273This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5274no effect in GNAT, other than being syntax checked. 5275 5276@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas 5277@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9f} 5278@section Pragma Max_Queue_Length 5279 5280 5281Syntax: 5282 5283@example 5284pragma Max_Entry_Queue (static_integer_EXPRESSION); 5285@end example 5286 5287This pragma is used to specify the maximum callers per entry queue for 5288individual protected entries and entry families. It accepts a single 5289positive integer as a parameter and must appear after the declaration 5290of an entry. 5291 5292@node Pragma No_Body,Pragma No_Component_Reordering,Pragma Max_Queue_Length,Implementation Defined Pragmas 5293@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a0} 5294@section Pragma No_Body 5295 5296 5297Syntax: 5298 5299@example 5300pragma No_Body; 5301@end example 5302 5303There are a number of cases in which a package spec does not require a body, 5304and in fact a body is not permitted. GNAT will not permit the spec to be 5305compiled if there is a body around. The pragma No_Body allows you to provide 5306a body file, even in a case where no body is allowed. The body file must 5307contain only comments and a single No_Body pragma. This is recognized by 5308the compiler as indicating that no body is logically present. 5309 5310This is particularly useful during maintenance when a package is modified in 5311such a way that a body needed before is no longer needed. The provision of a 5312dummy body with a No_Body pragma ensures that there is no interference from 5313earlier versions of the package body. 5314 5315@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Body,Implementation Defined Pragmas 5316@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a1} 5317@section Pragma No_Component_Reordering 5318 5319 5320Syntax: 5321 5322@example 5323pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 5324@end example 5325 5326@code{type_LOCAL_NAME} must refer to a record type declaration in the current 5327declarative part. The effect is to preclude any reordering of components 5328for the layout of the record, i.e. the record is laid out by the compiler 5329in the order in which the components are declared textually. The form with 5330no argument is a configuration pragma which applies to all record types 5331declared in units to which the pragma applies and there is a requirement 5332that this pragma be used consistently within a partition. 5333 5334@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas 5335@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a3} 5336@section Pragma No_Elaboration_Code_All 5337 5338 5339Syntax: 5340 5341@example 5342pragma No_Elaboration_Code_All [(program_unit_NAME)]; 5343@end example 5344 5345This is a program unit pragma (there is also an equivalent aspect of the 5346same name) that establishes the restriction @code{No_Elaboration_Code} for 5347the current unit and any extended main source units (body and subunits). 5348It also has the effect of enforcing a transitive application of this 5349aspect, so that if any unit is implicitly or explicitly with'ed by the 5350current unit, it must also have the No_Elaboration_Code_All aspect set. 5351It may be applied to package or subprogram specs or their generic versions. 5352 5353@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 5354@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a4} 5355@section Pragma No_Heap_Finalization 5356 5357 5358Syntax: 5359 5360@example 5361pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 5362@end example 5363 5364Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a 5365type-specific pragma. 5366 5367In its configuration form, the pragma must appear within a configuration file 5368such as gnat.adc, without an argument. The pragma suppresses the call to 5369@code{Finalize} for heap-allocated objects created through library-level named 5370access-to-object types in cases where the designated type requires finalization 5371actions. 5372 5373In its type-specific form, the argument of the pragma must denote a 5374library-level named access-to-object type. The pragma suppresses the call to 5375@code{Finalize} for heap-allocated objects created through the specific access type 5376in cases where the designated type requires finalization actions. 5377 5378It is still possible to finalize such heap-allocated objects by explicitly 5379deallocating them. 5380 5381A library-level named access-to-object type declared within a generic unit will 5382lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not 5383appear at the library level. 5384 5385@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas 5386@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a6} 5387@section Pragma No_Inline 5388 5389 5390Syntax: 5391 5392@example 5393pragma No_Inline (NAME @{, NAME@}); 5394@end example 5395 5396This pragma suppresses inlining for the callable entity or the instances of 5397the generic subprogram designated by @code{NAME}, including inlining that 5398results from the use of pragma @code{Inline}. This pragma is always active, 5399in particular it is not subject to the use of option @emph{-gnatn} or 5400@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 5401pragma @code{Inline_Always} for the same @code{NAME}. 5402 5403@node Pragma No_Return,Pragma No_Run_Time,Pragma No_Inline,Implementation Defined Pragmas 5404@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a7} 5405@section Pragma No_Return 5406 5407 5408Syntax: 5409 5410@example 5411pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5412@end example 5413 5414Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure 5415declarations in the current declarative part. A procedure to which this 5416pragma is applied may not contain any explicit @code{return} statements. 5417In addition, if the procedure contains any implicit returns from falling 5418off the end of a statement sequence, then execution of that implicit 5419return will cause Program_Error to be raised. 5420 5421One use of this pragma is to identify procedures whose only purpose is to raise 5422an exception. Another use of this pragma is to suppress incorrect warnings 5423about missing returns in functions, where the last statement of a function 5424statement sequence is a call to such a procedure. 5425 5426Note that in Ada 2005 mode, this pragma is part of the language. It is 5427available in all earlier versions of Ada as an implementation-defined 5428pragma. 5429 5430@node Pragma No_Run_Time,Pragma No_Strict_Aliasing,Pragma No_Return,Implementation Defined Pragmas 5431@anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{a8} 5432@section Pragma No_Run_Time 5433 5434 5435Syntax: 5436 5437@example 5438pragma No_Run_Time; 5439@end example 5440 5441This is an obsolete configuration pragma that historically was used to 5442set up a runtime library with no object code. It is now used only for 5443internal testing. The pragma has been superseded by the reconfigurable 5444runtime capability of GNAT. 5445 5446@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Run_Time,Implementation Defined Pragmas 5447@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a9} 5448@section Pragma No_Strict_Aliasing 5449 5450 5451Syntax: 5452 5453@example 5454pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5455@end example 5456 5457@code{type_LOCAL_NAME} must refer to an access type 5458declaration in the current declarative part. The effect is to inhibit 5459strict aliasing optimization for the given type. The form with no 5460arguments is a configuration pragma which applies to all access types 5461declared in units to which the pragma applies. For a detailed 5462description of the strict aliasing optimization, and the situations 5463in which it must be suppressed, see the section on Optimization and Strict Aliasing 5464in the @cite{GNAT User's Guide}. 5465 5466This pragma currently has no effects on access to unconstrained array types. 5467 5468@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5469@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{aa}@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{ab} 5470@section Pragma No_Tagged_Streams 5471 5472 5473Syntax: 5474 5475@example 5476pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5477@end example 5478 5479Normally when a tagged type is introduced using a full type declaration, 5480part of the processing includes generating stream access routines to be 5481used by stream attributes referencing the type (or one of its subtypes 5482or derived types). This can involve the generation of significant amounts 5483of code which is wasted space if stream routines are not needed for the 5484type in question. 5485 5486The @code{No_Tagged_Streams} pragma causes the generation of these stream 5487routines to be skipped, and any attempt to use stream operations on 5488types subject to this pragma will be statically rejected as illegal. 5489 5490There are two forms of the pragma. The form with no arguments must appear 5491in a declarative sequence or in the declarations of a package spec. This 5492pragma affects all subsequent root tagged types declared in the declaration 5493sequence, and specifies that no stream routines be generated. The form with 5494an argument (for which there is also a corresponding aspect) specifies a 5495single root tagged type for which stream routines are not to be generated. 5496 5497Once the pragma has been given for a particular root tagged type, all subtypes 5498and derived types of this type inherit the pragma automatically, so the effect 5499applies to a complete hierarchy (this is necessary to deal with the class-wide 5500dispatching versions of the stream routines). 5501 5502When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously 5503applied to a tagged type its Expanded_Name and External_Tag are initialized 5504with empty strings. This is useful to avoid exposing entity names at binary 5505level but has a negative impact on the debuggability of tagged types. 5506 5507@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5508@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ac} 5509@section Pragma Normalize_Scalars 5510 5511 5512Syntax: 5513 5514@example 5515pragma Normalize_Scalars; 5516@end example 5517 5518This is a language defined pragma which is fully implemented in GNAT. The 5519effect is to cause all scalar objects that are not otherwise initialized 5520to be initialized. The initial values are implementation dependent and 5521are as follows: 5522 5523 5524@table @asis 5525 5526@item @emph{Standard.Character} 5527 5528Objects whose root type is Standard.Character are initialized to 5529Character'Last unless the subtype range excludes NUL (in which case 5530NUL is used). This choice will always generate an invalid value if 5531one exists. 5532 5533@item @emph{Standard.Wide_Character} 5534 5535Objects whose root type is Standard.Wide_Character are initialized to 5536Wide_Character'Last unless the subtype range excludes NUL (in which case 5537NUL is used). This choice will always generate an invalid value if 5538one exists. 5539 5540@item @emph{Standard.Wide_Wide_Character} 5541 5542Objects whose root type is Standard.Wide_Wide_Character are initialized to 5543the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5544which case NUL is used). This choice will always generate an invalid value if 5545one exists. 5546 5547@item @emph{Integer types} 5548 5549Objects of an integer type are treated differently depending on whether 5550negative values are present in the subtype. If no negative values are 5551present, then all one bits is used as the initial value except in the 5552special case where zero is excluded from the subtype, in which case 5553all zero bits are used. This choice will always generate an invalid 5554value if one exists. 5555 5556For subtypes with negative values present, the largest negative number 5557is used, except in the unusual case where this largest negative number 5558is in the subtype, and the largest positive number is not, in which case 5559the largest positive value is used. This choice will always generate 5560an invalid value if one exists. 5561 5562@item @emph{Floating-Point Types} 5563 5564Objects of all floating-point types are initialized to all 1-bits. For 5565standard IEEE format, this corresponds to a NaN (not a number) which is 5566indeed an invalid value. 5567 5568@item @emph{Fixed-Point Types} 5569 5570Objects of all fixed-point types are treated as described above for integers, 5571with the rules applying to the underlying integer value used to represent 5572the fixed-point value. 5573 5574@item @emph{Modular types} 5575 5576Objects of a modular type are initialized to all one bits, except in 5577the special case where zero is excluded from the subtype, in which 5578case all zero bits are used. This choice will always generate an 5579invalid value if one exists. 5580 5581@item @emph{Enumeration types} 5582 5583Objects of an enumeration type are initialized to all one-bits, i.e., to 5584the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 5585whose Pos value is zero, in which case a code of zero is used. This choice 5586will always generate an invalid value if one exists. 5587@end table 5588 5589@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5590@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ad}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{ae} 5591@section Pragma Obsolescent 5592 5593 5594Syntax: 5595 5596@example 5597pragma Obsolescent; 5598 5599pragma Obsolescent ( 5600 [Message =>] static_string_EXPRESSION 5601[,[Version =>] Ada_05]]); 5602 5603pragma Obsolescent ( 5604 [Entity =>] NAME 5605[,[Message =>] static_string_EXPRESSION 5606[,[Version =>] Ada_05]] ); 5607@end example 5608 5609This pragma can occur immediately following a declaration of an entity, 5610including the case of a record component. If no Entity argument is present, 5611then this declaration is the one to which the pragma applies. If an Entity 5612parameter is present, it must either match the name of the entity in this 5613declaration, or alternatively, the pragma can immediately follow an enumeration 5614type declaration, where the Entity argument names one of the enumeration 5615literals. 5616 5617This pragma is used to indicate that the named entity 5618is considered obsolescent and should not be used. Typically this is 5619used when an API must be modified by eventually removing or modifying 5620existing subprograms or other entities. The pragma can be used at an 5621intermediate stage when the entity is still present, but will be 5622removed later. 5623 5624The effect of this pragma is to output a warning message on a reference to 5625an entity thus marked that the subprogram is obsolescent if the appropriate 5626warning option in the compiler is activated. If the @code{Message} parameter is 5627present, then a second warning message is given containing this text. In 5628addition, a reference to the entity is considered to be a violation of pragma 5629@code{Restrictions (No_Obsolescent_Features)}. 5630 5631This pragma can also be used as a program unit pragma for a package, 5632in which case the entity name is the name of the package, and the 5633pragma indicates that the entire package is considered 5634obsolescent. In this case a client @code{with}ing such a package 5635violates the restriction, and the @code{with} clause is 5636flagged with warnings if the warning option is set. 5637 5638If the @code{Version} parameter is present (which must be exactly 5639the identifier @code{Ada_05}, no other argument is allowed), then the 5640indication of obsolescence applies only when compiling in Ada 2005 5641mode. This is primarily intended for dealing with the situations 5642in the predefined library where subprograms or packages 5643have become defined as obsolescent in Ada 2005 5644(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. 5645 5646The following examples show typical uses of this pragma: 5647 5648@example 5649package p is 5650 pragma Obsolescent (p, Message => "use pp instead of p"); 5651end p; 5652 5653package q is 5654 procedure q2; 5655 pragma Obsolescent ("use q2new instead"); 5656 5657 type R is new integer; 5658 pragma Obsolescent 5659 (Entity => R, 5660 Message => "use RR in Ada 2005", 5661 Version => Ada_05); 5662 5663 type M is record 5664 F1 : Integer; 5665 F2 : Integer; 5666 pragma Obsolescent; 5667 F3 : Integer; 5668 end record; 5669 5670 type E is (a, bc, 'd', quack); 5671 pragma Obsolescent (Entity => bc) 5672 pragma Obsolescent (Entity => 'd') 5673 5674 function "+" 5675 (a, b : character) return character; 5676 pragma Obsolescent (Entity => "+"); 5677end; 5678@end example 5679 5680Note that, as for all pragmas, if you use a pragma argument identifier, 5681then all subsequent parameters must also use a pragma argument identifier. 5682So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} 5683argument is present, it must be preceded by @code{Message =>}. 5684 5685@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5686@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{af} 5687@section Pragma Optimize_Alignment 5688 5689 5690@geindex Alignment 5691@geindex default settings 5692 5693Syntax: 5694 5695@example 5696pragma Optimize_Alignment (TIME | SPACE | OFF); 5697@end example 5698 5699This is a configuration pragma which affects the choice of default alignments 5700for types and objects where no alignment is explicitly specified. There is a 5701time/space trade-off in the selection of these values. Large alignments result 5702in more efficient code, at the expense of larger data space, since sizes have 5703to be increased to match these alignments. Smaller alignments save space, but 5704the access code is slower. The normal choice of default alignments for types 5705and individual alignment promotions for objects (which is what you get if you 5706do not use this pragma, or if you use an argument of OFF), tries to balance 5707these two requirements. 5708 5709Specifying SPACE causes smaller default alignments to be chosen in two cases. 5710First any packed record is given an alignment of 1. Second, if a size is given 5711for the type, then the alignment is chosen to avoid increasing this size. For 5712example, consider: 5713 5714@example 5715type R is record 5716 X : Integer; 5717 Y : Character; 5718end record; 5719 5720for R'Size use 5*8; 5721@end example 5722 5723In the default mode, this type gets an alignment of 4, so that access to the 5724Integer field X are efficient. But this means that objects of the type end up 5725with a size of 8 bytes. This is a valid choice, since sizes of objects are 5726allowed to be bigger than the size of the type, but it can waste space if for 5727example fields of type R appear in an enclosing record. If the above type is 5728compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5729 5730However, there is one case in which SPACE is ignored. If a variable length 5731record (that is a discriminated record with a component which is an array 5732whose length depends on a discriminant), has a pragma Pack, then it is not 5733in general possible to set the alignment of such a record to one, so the 5734pragma is ignored in this case (with a warning). 5735 5736Specifying SPACE also disables alignment promotions for standalone objects, 5737which occur when the compiler increases the alignment of a specific object 5738without changing the alignment of its type. 5739 5740Specifying SPACE also disables component reordering in unpacked record types, 5741which can result in larger sizes in order to meet alignment requirements. 5742 5743Specifying TIME causes larger default alignments to be chosen in the case of 5744small types with sizes that are not a power of 2. For example, consider: 5745 5746@example 5747type R is record 5748 A : Character; 5749 B : Character; 5750 C : Boolean; 5751end record; 5752 5753pragma Pack (R); 5754for R'Size use 17; 5755@end example 5756 5757The default alignment for this record is normally 1, but if this type is 5758compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 5759to 4, which wastes space for objects of the type, since they are now 4 bytes 5760long, but results in more efficient access when the whole record is referenced. 5761 5762As noted above, this is a configuration pragma, and there is a requirement 5763that all units in a partition be compiled with a consistent setting of the 5764optimization setting. This would normally be achieved by use of a configuration 5765pragma file containing the appropriate setting. The exception to this rule is 5766that units with an explicit configuration pragma in the same file as the source 5767unit are excluded from the consistency check, as are all predefined units. The 5768latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5769pragma appears at the start of the file. 5770 5771@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5772@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b0} 5773@section Pragma Ordered 5774 5775 5776Syntax: 5777 5778@example 5779pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5780@end example 5781 5782Most enumeration types are from a conceptual point of view unordered. 5783For example, consider: 5784 5785@example 5786type Color is (Red, Blue, Green, Yellow); 5787@end example 5788 5789By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 5790but really these relations make no sense; the enumeration type merely 5791specifies a set of possible colors, and the order is unimportant. 5792 5793For unordered enumeration types, it is generally a good idea if 5794clients avoid comparisons (other than equality or inequality) and 5795explicit ranges. (A @emph{client} is a unit where the type is referenced, 5796other than the unit where the type is declared, its body, and its subunits.) 5797For example, if code buried in some client says: 5798 5799@example 5800if Current_Color < Yellow then ... 5801if Current_Color in Blue .. Green then ... 5802@end example 5803 5804then the client code is relying on the order, which is undesirable. 5805It makes the code hard to read and creates maintenance difficulties if 5806entries have to be added to the enumeration type. Instead, 5807the code in the client should list the possibilities, or an 5808appropriate subtype should be declared in the unit that declares 5809the original enumeration type. E.g., the following subtype could 5810be declared along with the type @code{Color}: 5811 5812@example 5813subtype RBG is Color range Red .. Green; 5814@end example 5815 5816and then the client could write: 5817 5818@example 5819if Current_Color in RBG then ... 5820if Current_Color = Blue or Current_Color = Green then ... 5821@end example 5822 5823However, some enumeration types are legitimately ordered from a conceptual 5824point of view. For example, if you declare: 5825 5826@example 5827type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5828@end example 5829 5830then the ordering imposed by the language is reasonable, and 5831clients can depend on it, writing for example: 5832 5833@example 5834if D in Mon .. Fri then ... 5835if D < Wed then ... 5836@end example 5837 5838The pragma @emph{Ordered} is provided to mark enumeration types that 5839are conceptually ordered, alerting the reader that clients may depend 5840on the ordering. GNAT provides a pragma to mark enumerations as ordered 5841rather than one to mark them as unordered, since in our experience, 5842the great majority of enumeration types are conceptually unordered. 5843 5844The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 5845and @code{Wide_Wide_Character} 5846are considered to be ordered types, so each is declared with a 5847pragma @code{Ordered} in package @code{Standard}. 5848 5849Normally pragma @code{Ordered} serves only as documentation and a guide for 5850coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 5851requests warnings for inappropriate uses (comparisons and explicit 5852subranges) for unordered types. If this switch is used, then any 5853enumeration type not marked with pragma @code{Ordered} will be considered 5854as unordered, and will generate warnings for inappropriate uses. 5855 5856Note that generic types are not considered ordered or unordered (since the 5857template can be instantiated for both cases), so we never generate warnings 5858for the case of generic enumerated types. 5859 5860For additional information please refer to the description of the 5861@emph{-gnatw.u} switch in the GNAT User's Guide. 5862 5863@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 5864@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b1} 5865@section Pragma Overflow_Mode 5866 5867 5868Syntax: 5869 5870@example 5871pragma Overflow_Mode 5872 ( [General =>] MODE 5873 [,[Assertions =>] MODE]); 5874 5875MODE ::= STRICT | MINIMIZED | ELIMINATED 5876@end example 5877 5878This pragma sets the current overflow mode to the given setting. For details 5879of the meaning of these modes, please refer to the 5880'Overflow Check Handling in GNAT' appendix in the 5881GNAT User's Guide. If only the @code{General} parameter is present, 5882the given mode applies to all expressions. If both parameters are present, 5883the @code{General} mode applies to expressions outside assertions, and 5884the @code{Eliminated} mode applies to expressions within assertions. 5885 5886The case of the @code{MODE} parameter is ignored, 5887so @code{MINIMIZED}, @code{Minimized} and 5888@code{minimized} all have the same effect. 5889 5890The @code{Overflow_Mode} pragma has the same scoping and placement 5891rules as pragma @code{Suppress}, so it can occur either as a 5892configuration pragma, specifying a default for the whole 5893program, or in a declarative scope, where it applies to the 5894remaining declarations and statements in that scope. 5895 5896The pragma @code{Suppress (Overflow_Check)} suppresses 5897overflow checking, but does not affect the overflow mode. 5898 5899The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 5900overflow checking, but does not affect the overflow mode. 5901 5902@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 5903@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b2} 5904@section Pragma Overriding_Renamings 5905 5906 5907@geindex Rational profile 5908 5909@geindex Rational compatibility 5910 5911Syntax: 5912 5913@example 5914pragma Overriding_Renamings; 5915@end example 5916 5917This is a GNAT configuration pragma to simplify porting 5918legacy code accepted by the Rational 5919Ada compiler. In the presence of this pragma, a renaming declaration that 5920renames an inherited operation declared in the same scope is legal if selected 5921notation is used as in: 5922 5923@example 5924pragma Overriding_Renamings; 5925... 5926package R is 5927 function F (..); 5928 ... 5929 function F (..) renames R.F; 5930end R; 5931@end example 5932 5933even though 5934RM 8.3 (15) stipulates that an overridden operation is not visible within the 5935declaration of the overriding operation. 5936 5937@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 5938@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b3} 5939@section Pragma Partition_Elaboration_Policy 5940 5941 5942Syntax: 5943 5944@example 5945pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 5946 5947POLICY_IDENTIFIER ::= Concurrent | Sequential 5948@end example 5949 5950This pragma is standard in Ada 2005, but is available in all earlier 5951versions of Ada as an implementation-defined pragma. 5952See Ada 2012 Reference Manual for details. 5953 5954@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 5955@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{b4}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b5} 5956@section Pragma Part_Of 5957 5958 5959Syntax: 5960 5961@example 5962pragma Part_Of (ABSTRACT_STATE); 5963 5964ABSTRACT_STATE ::= NAME 5965@end example 5966 5967For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the 5968SPARK 2014 Reference Manual, section 7.2.6. 5969 5970@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 5971@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b6} 5972@section Pragma Passive 5973 5974 5975Syntax: 5976 5977@example 5978pragma Passive [(Semaphore | No)]; 5979@end example 5980 5981Syntax checked, but otherwise ignored by GNAT. This is recognized for 5982compatibility with DEC Ada 83 implementations, where it is used within a 5983task definition to request that a task be made passive. If the argument 5984@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 5985treats the pragma as an assertion that the containing task is passive 5986and that optimization of context switch with this task is permitted and 5987desired. If the argument @code{No} is present, the task must not be 5988optimized. GNAT does not attempt to optimize any tasks in this manner 5989(since protected objects are available in place of passive tasks). 5990 5991For more information on the subject of passive tasks, see the section 5992'Passive Task Optimization' in the GNAT Users Guide. 5993 5994@node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas 5995@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b7}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b8} 5996@section Pragma Persistent_BSS 5997 5998 5999Syntax: 6000 6001@example 6002pragma Persistent_BSS [(LOCAL_NAME)] 6003@end example 6004 6005This pragma allows selected objects to be placed in the @code{.persistent_bss} 6006section. On some targets the linker and loader provide for special 6007treatment of this section, allowing a program to be reloaded without 6008affecting the contents of this data (hence the name persistent). 6009 6010There are two forms of usage. If an argument is given, it must be the 6011local name of a library-level object, with no explicit initialization 6012and whose type is potentially persistent. If no argument is given, then 6013the pragma is a configuration pragma, and applies to all library-level 6014objects with no explicit initialization of potentially persistent types. 6015 6016A potentially persistent type is a scalar type, or an untagged, 6017non-discriminated record, all of whose components have no explicit 6018initialization and are themselves of a potentially persistent type, 6019or an array, all of whose constraints are static, and whose component 6020type is potentially persistent. 6021 6022If this pragma is used on a target where this feature is not supported, 6023then the pragma will be ignored. See also @code{pragma Linker_Section}. 6024 6025@node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas 6026@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{b9} 6027@section Pragma Polling 6028 6029 6030Syntax: 6031 6032@example 6033pragma Polling (ON | OFF); 6034@end example 6035 6036This pragma controls the generation of polling code. This is normally off. 6037If @code{pragma Polling (ON)} is used then periodic calls are generated to 6038the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 6039runtime library, and can be found in file @code{a-excpol.adb}. 6040 6041Pragma @code{Polling} can appear as a configuration pragma (for example it 6042can be placed in the @code{gnat.adc} file) to enable polling globally, or it 6043can be used in the statement or declaration sequence to control polling 6044more locally. 6045 6046A call to the polling routine is generated at the start of every loop and 6047at the start of every subprogram call. This guarantees that the @code{Poll} 6048routine is called frequently, and places an upper bound (determined by 6049the complexity of the code) on the period between two @code{Poll} calls. 6050 6051The primary purpose of the polling interface is to enable asynchronous 6052aborts on targets that cannot otherwise support it (for example Windows 6053NT), but it may be used for any other purpose requiring periodic polling. 6054The standard version is null, and can be replaced by a user program. This 6055will require re-compilation of the @code{Ada.Exceptions} package that can 6056be found in files @code{a-except.ads} and @code{a-except.adb}. 6057 6058A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT 6059distribution) is used to enable the asynchronous abort capability on 6060targets that do not normally support the capability. The version of 6061@code{Poll} in this file makes a call to the appropriate runtime routine 6062to test for an abort condition. 6063 6064Note that polling can also be enabled by use of the @emph{-gnatP} switch. 6065See the section on switches for gcc in the @cite{GNAT User's Guide}. 6066 6067@node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas 6068@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{ba} 6069@section Pragma Post 6070 6071 6072@geindex Post 6073 6074@geindex Checks 6075@geindex postconditions 6076 6077Syntax: 6078 6079@example 6080pragma Post (Boolean_Expression); 6081@end example 6082 6083The @code{Post} pragma is intended to be an exact replacement for 6084the language-defined 6085@code{Post} aspect, and shares its restrictions and semantics. 6086It must appear either immediately following the corresponding 6087subprogram declaration (only other pragmas may intervene), or 6088if there is no separate subprogram declaration, then it can 6089appear at the start of the declarations in a subprogram body 6090(preceded only by other pragmas). 6091 6092@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 6093@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{bb} 6094@section Pragma Postcondition 6095 6096 6097@geindex Postcondition 6098 6099@geindex Checks 6100@geindex postconditions 6101 6102Syntax: 6103 6104@example 6105pragma Postcondition ( 6106 [Check =>] Boolean_Expression 6107 [,[Message =>] String_Expression]); 6108@end example 6109 6110The @code{Postcondition} pragma allows specification of automatic 6111postcondition checks for subprograms. These checks are similar to 6112assertions, but are automatically inserted just prior to the return 6113statements of the subprogram with which they are associated (including 6114implicit returns at the end of procedure bodies and associated 6115exception handlers). 6116 6117In addition, the boolean expression which is the condition which 6118must be true may contain references to function'Result in the case 6119of a function to refer to the returned value. 6120 6121@code{Postcondition} pragmas may appear either immediately following the 6122(separate) declaration of a subprogram, or at the start of the 6123declarations of a subprogram body. Only other pragmas may intervene 6124(that is appear between the subprogram declaration and its 6125postconditions, or appear before the postcondition in the 6126declaration sequence in a subprogram body). In the case of a 6127postcondition appearing after a subprogram declaration, the 6128formal arguments of the subprogram are visible, and can be 6129referenced in the postcondition expressions. 6130 6131The postconditions are collected and automatically tested just 6132before any return (implicit or explicit) in the subprogram body. 6133A postcondition is only recognized if postconditions are active 6134at the time the pragma is encountered. The compiler switch @emph{gnata} 6135turns on all postconditions by default, and pragma @code{Check_Policy} 6136with an identifier of @code{Postcondition} can also be used to 6137control whether postconditions are active. 6138 6139The general approach is that postconditions are placed in the spec 6140if they represent functional aspects which make sense to the client. 6141For example we might have: 6142 6143@example 6144function Direction return Integer; 6145pragma Postcondition 6146 (Direction'Result = +1 6147 or else 6148 Direction'Result = -1); 6149@end example 6150 6151which serves to document that the result must be +1 or -1, and 6152will test that this is the case at run time if postcondition 6153checking is active. 6154 6155Postconditions within the subprogram body can be used to 6156check that some internal aspect of the implementation, 6157not visible to the client, is operating as expected. 6158For instance if a square root routine keeps an internal 6159counter of the number of times it is called, then we 6160might have the following postcondition: 6161 6162@example 6163Sqrt_Calls : Natural := 0; 6164 6165function Sqrt (Arg : Float) return Float is 6166 pragma Postcondition 6167 (Sqrt_Calls = Sqrt_Calls'Old + 1); 6168 ... 6169end Sqrt 6170@end example 6171 6172As this example, shows, the use of the @code{Old} attribute 6173is often useful in postconditions to refer to the state on 6174entry to the subprogram. 6175 6176Note that postconditions are only checked on normal returns 6177from the subprogram. If an abnormal return results from 6178raising an exception, then the postconditions are not checked. 6179 6180If a postcondition fails, then the exception 6181@code{System.Assertions.Assert_Failure} is raised. If 6182a message argument was supplied, then the given string 6183will be used as the exception message. If no message 6184argument was supplied, then the default message has 6185the form "Postcondition failed at file_name:line". The 6186exception is raised in the context of the subprogram 6187body, so it is possible to catch postcondition failures 6188within the subprogram body itself. 6189 6190Within a package spec, normal visibility rules 6191in Ada would prevent forward references within a 6192postcondition pragma to functions defined later in 6193the same package. This would introduce undesirable 6194ordering constraints. To avoid this problem, all 6195postcondition pragmas are analyzed at the end of 6196the package spec, allowing forward references. 6197 6198The following example shows that this even allows 6199mutually recursive postconditions as in: 6200 6201@example 6202package Parity_Functions is 6203 function Odd (X : Natural) return Boolean; 6204 pragma Postcondition 6205 (Odd'Result = 6206 (x = 1 6207 or else 6208 (x /= 0 and then Even (X - 1)))); 6209 6210 function Even (X : Natural) return Boolean; 6211 pragma Postcondition 6212 (Even'Result = 6213 (x = 0 6214 or else 6215 (x /= 1 and then Odd (X - 1)))); 6216 6217end Parity_Functions; 6218@end example 6219 6220There are no restrictions on the complexity or form of 6221conditions used within @code{Postcondition} pragmas. 6222The following example shows that it is even possible 6223to verify performance behavior. 6224 6225@example 6226package Sort is 6227 6228 Performance : constant Float; 6229 -- Performance constant set by implementation 6230 -- to match target architecture behavior. 6231 6232 procedure Treesort (Arg : String); 6233 -- Sorts characters of argument using N*logN sort 6234 pragma Postcondition 6235 (Float (Clock - Clock'Old) <= 6236 Float (Arg'Length) * 6237 log (Float (Arg'Length)) * 6238 Performance); 6239end Sort; 6240@end example 6241 6242Note: postcondition pragmas associated with subprograms that are 6243marked as Inline_Always, or those marked as Inline with front-end 6244inlining (-gnatN option set) are accepted and legality-checked 6245by the compiler, but are ignored at run-time even if postcondition 6246checking is enabled. 6247 6248Note that pragma @code{Postcondition} differs from the language-defined 6249@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 6250multiple occurrences, allowing occurences in the body even if there 6251is a separate spec, and allowing a second string parameter, and the 6252use of the pragma identifier @code{Check}. Historically, pragma 6253@code{Postcondition} was implemented prior to the development of 6254Ada 2012, and has been retained in its original form for 6255compatibility purposes. 6256 6257@node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas 6258@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{bc} 6259@section Pragma Post_Class 6260 6261 6262@geindex Post 6263 6264@geindex Checks 6265@geindex postconditions 6266 6267Syntax: 6268 6269@example 6270pragma Post_Class (Boolean_Expression); 6271@end example 6272 6273The @code{Post_Class} pragma is intended to be an exact replacement for 6274the language-defined 6275@code{Post'Class} aspect, and shares its restrictions and semantics. 6276It must appear either immediately following the corresponding 6277subprogram declaration (only other pragmas may intervene), or 6278if there is no separate subprogram declaration, then it can 6279appear at the start of the declarations in a subprogram body 6280(preceded only by other pragmas). 6281 6282Note: This pragma is called @code{Post_Class} rather than 6283@code{Post'Class} because the latter would not be strictly 6284conforming to the allowed syntax for pragmas. The motivation 6285for provinding pragmas equivalent to the aspects is to allow a program 6286to be written using the pragmas, and then compiled if necessary 6287using an Ada compiler that does not recognize the pragmas or 6288aspects, but is prepared to ignore the pragmas. The assertion 6289policy that controls this pragma is @code{Post'Class}, not 6290@code{Post_Class}. 6291 6292@node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas 6293@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{bd} 6294@section Pragma Rename_Pragma 6295 6296 6297@geindex Pragmas 6298@geindex synonyms 6299 6300Syntax: 6301 6302@example 6303pragma Rename_Pragma ( 6304 [New_Name =>] IDENTIFIER, 6305 [Renamed =>] pragma_IDENTIFIER); 6306@end example 6307 6308This pragma provides a mechanism for supplying new names for existing 6309pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for 6310the Renamed pragma. For example, suppose you have code that was originally 6311developed on a compiler that supports Inline_Only as an implementation defined 6312pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 6313least very similar to) the GNAT implementation defined pragma 6314Inline_Always. You could globally replace Inline_Only with Inline_Always. 6315 6316However, to avoid that source modification, you could instead add a 6317configuration pragma: 6318 6319@example 6320pragma Rename_Pragma ( 6321 New_Name => Inline_Only, 6322 Renamed => Inline_Always); 6323@end example 6324 6325Then GNAT will treat "pragma Inline_Only ..." as if you had written 6326"pragma Inline_Always ...". 6327 6328Pragma Inline_Only will not necessarily mean the same thing as the other Ada 6329compiler; it's up to you to make sure the semantics are close enough. 6330 6331@node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas 6332@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{be} 6333@section Pragma Pre 6334 6335 6336@geindex Pre 6337 6338@geindex Checks 6339@geindex preconditions 6340 6341Syntax: 6342 6343@example 6344pragma Pre (Boolean_Expression); 6345@end example 6346 6347The @code{Pre} pragma is intended to be an exact replacement for 6348the language-defined 6349@code{Pre} aspect, and shares its restrictions and semantics. 6350It must appear either immediately following the corresponding 6351subprogram declaration (only other pragmas may intervene), or 6352if there is no separate subprogram declaration, then it can 6353appear at the start of the declarations in a subprogram body 6354(preceded only by other pragmas). 6355 6356@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 6357@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bf} 6358@section Pragma Precondition 6359 6360 6361@geindex Preconditions 6362 6363@geindex Checks 6364@geindex preconditions 6365 6366Syntax: 6367 6368@example 6369pragma Precondition ( 6370 [Check =>] Boolean_Expression 6371 [,[Message =>] String_Expression]); 6372@end example 6373 6374The @code{Precondition} pragma is similar to @code{Postcondition} 6375except that the corresponding checks take place immediately upon 6376entry to the subprogram, and if a precondition fails, the exception 6377is raised in the context of the caller, and the attribute 'Result 6378cannot be used within the precondition expression. 6379 6380Otherwise, the placement and visibility rules are identical to those 6381described for postconditions. The following is an example of use 6382within a package spec: 6383 6384@example 6385package Math_Functions is 6386 ... 6387 function Sqrt (Arg : Float) return Float; 6388 pragma Precondition (Arg >= 0.0) 6389 ... 6390end Math_Functions; 6391@end example 6392 6393@code{Precondition} pragmas may appear either immediately following the 6394(separate) declaration of a subprogram, or at the start of the 6395declarations of a subprogram body. Only other pragmas may intervene 6396(that is appear between the subprogram declaration and its 6397postconditions, or appear before the postcondition in the 6398declaration sequence in a subprogram body). 6399 6400Note: precondition pragmas associated with subprograms that are 6401marked as Inline_Always, or those marked as Inline with front-end 6402inlining (-gnatN option set) are accepted and legality-checked 6403by the compiler, but are ignored at run-time even if precondition 6404checking is enabled. 6405 6406Note that pragma @code{Precondition} differs from the language-defined 6407@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 6408multiple occurrences, allowing occurences in the body even if there 6409is a separate spec, and allowing a second string parameter, and the 6410use of the pragma identifier @code{Check}. Historically, pragma 6411@code{Precondition} was implemented prior to the development of 6412Ada 2012, and has been retained in its original form for 6413compatibility purposes. 6414 6415@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 6416@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{c0}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c1} 6417@section Pragma Predicate 6418 6419 6420Syntax: 6421 6422@example 6423pragma Predicate 6424 ([Entity =>] type_LOCAL_NAME, 6425 [Check =>] EXPRESSION); 6426@end example 6427 6428This pragma (available in all versions of Ada in GNAT) encompasses both 6429the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 6430Ada 2012. A predicate is regarded as static if it has an allowed form 6431for @code{Static_Predicate} and is otherwise treated as a 6432@code{Dynamic_Predicate}. Otherwise, predicates specified by this 6433pragma behave exactly as described in the Ada 2012 reference manual. 6434For example, if we have 6435 6436@example 6437type R is range 1 .. 10; 6438subtype S is R; 6439pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6440subtype Q is R 6441pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6442@end example 6443 6444the effect is identical to the following Ada 2012 code: 6445 6446@example 6447type R is range 1 .. 10; 6448subtype S is R with 6449 Static_Predicate => S not in 4 .. 6; 6450subtype Q is R with 6451 Dynamic_Predicate => F(Q) or G(Q); 6452@end example 6453 6454Note that there are no pragmas @code{Dynamic_Predicate} 6455or @code{Static_Predicate}. That is 6456because these pragmas would affect legality and semantics of 6457the program and thus do not have a neutral effect if ignored. 6458The motivation behind providing pragmas equivalent to 6459corresponding aspects is to allow a program to be written 6460using the pragmas, and then compiled with a compiler that 6461will ignore the pragmas. That doesn't work in the case of 6462static and dynamic predicates, since if the corresponding 6463pragmas are ignored, then the behavior of the program is 6464fundamentally changed (for example a membership test 6465@code{A in B} would not take into account a predicate 6466defined for subtype B). When following this approach, the 6467use of predicates should be avoided. 6468 6469@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6470@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c2} 6471@section Pragma Predicate_Failure 6472 6473 6474Syntax: 6475 6476@example 6477pragma Predicate_Failure 6478 ([Entity =>] type_LOCAL_NAME, 6479 [Message =>] String_Expression); 6480@end example 6481 6482The @code{Predicate_Failure} pragma is intended to be an exact replacement for 6483the language-defined 6484@code{Predicate_Failure} aspect, and shares its restrictions and semantics. 6485 6486@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6487@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c3} 6488@section Pragma Preelaborable_Initialization 6489 6490 6491Syntax: 6492 6493@example 6494pragma Preelaborable_Initialization (DIRECT_NAME); 6495@end example 6496 6497This pragma is standard in Ada 2005, but is available in all earlier 6498versions of Ada as an implementation-defined pragma. 6499See Ada 2012 Reference Manual for details. 6500 6501@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6502@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c4} 6503@section Pragma Prefix_Exception_Messages 6504 6505 6506@geindex Prefix_Exception_Messages 6507 6508@geindex exception 6509 6510@geindex Exception_Message 6511 6512Syntax: 6513 6514@example 6515pragma Prefix_Exception_Messages; 6516@end example 6517 6518This is an implementation-defined configuration pragma that affects the 6519behavior of raise statements with a message given as a static string 6520constant (typically a string literal). In such cases, the string will 6521be automatically prefixed by the name of the enclosing entity (giving 6522the package and subprogram containing the raise statement). This helps 6523to identify where messages are coming from, and this mode is automatic 6524for the run-time library. 6525 6526The pragma has no effect if the message is computed with an expression other 6527than a static string constant, since the assumption in this case is that 6528the program computes exactly the string it wants. If you still want the 6529prefixing in this case, you can always call 6530@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6531 6532@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6533@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c5} 6534@section Pragma Pre_Class 6535 6536 6537@geindex Pre_Class 6538 6539@geindex Checks 6540@geindex preconditions 6541 6542Syntax: 6543 6544@example 6545pragma Pre_Class (Boolean_Expression); 6546@end example 6547 6548The @code{Pre_Class} pragma is intended to be an exact replacement for 6549the language-defined 6550@code{Pre'Class} aspect, and shares its restrictions and semantics. 6551It must appear either immediately following the corresponding 6552subprogram declaration (only other pragmas may intervene), or 6553if there is no separate subprogram declaration, then it can 6554appear at the start of the declarations in a subprogram body 6555(preceded only by other pragmas). 6556 6557Note: This pragma is called @code{Pre_Class} rather than 6558@code{Pre'Class} because the latter would not be strictly 6559conforming to the allowed syntax for pragmas. The motivation 6560for providing pragmas equivalent to the aspects is to allow a program 6561to be written using the pragmas, and then compiled if necessary 6562using an Ada compiler that does not recognize the pragmas or 6563aspects, but is prepared to ignore the pragmas. The assertion 6564policy that controls this pragma is @code{Pre'Class}, not 6565@code{Pre_Class}. 6566 6567@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6568@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c6} 6569@section Pragma Priority_Specific_Dispatching 6570 6571 6572Syntax: 6573 6574@example 6575pragma Priority_Specific_Dispatching ( 6576 POLICY_IDENTIFIER, 6577 first_priority_EXPRESSION, 6578 last_priority_EXPRESSION) 6579 6580POLICY_IDENTIFIER ::= 6581 EDF_Across_Priorities | 6582 FIFO_Within_Priorities | 6583 Non_Preemptive_Within_Priorities | 6584 Round_Robin_Within_Priorities 6585@end example 6586 6587This pragma is standard in Ada 2005, but is available in all earlier 6588versions of Ada as an implementation-defined pragma. 6589See Ada 2012 Reference Manual for details. 6590 6591@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6592@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c7} 6593@section Pragma Profile 6594 6595 6596Syntax: 6597 6598@example 6599pragma Profile (Ravenscar | Restricted | Rational | 6600 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 6601@end example 6602 6603This pragma is standard in Ada 2005, but is available in all earlier 6604versions of Ada as an implementation-defined pragma. This is a 6605configuration pragma that establishes a set of configuration pragmas 6606that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 6607The other possibilities (@code{Restricted}, @code{Rational}, 6608@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) 6609are implementation-defined. The set of configuration pragmas 6610is defined in the following sections. 6611 6612 6613@itemize * 6614 6615@item 6616Pragma Profile (Ravenscar) 6617 6618The @code{Ravenscar} profile is standard in Ada 2005, 6619but is available in all earlier 6620versions of Ada as an implementation-defined pragma. This profile 6621establishes the following set of configuration pragmas: 6622 6623 6624@itemize * 6625 6626@item 6627@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6628 6629[RM D.2.2] Tasks are dispatched following a preemptive 6630priority-ordered scheduling policy. 6631 6632@item 6633@code{Locking_Policy (Ceiling_Locking)} 6634 6635[RM D.3] While tasks and interrupts execute a protected action, they inherit 6636the ceiling priority of the corresponding protected object. 6637 6638@item 6639@code{Detect_Blocking} 6640 6641This pragma forces the detection of potentially blocking operations within a 6642protected operation, and to raise Program_Error if that happens. 6643@end itemize 6644 6645plus the following set of restrictions: 6646 6647 6648@itemize * 6649 6650@item 6651@code{Max_Entry_Queue_Length => 1} 6652 6653No task can be queued on a protected entry. 6654 6655@item 6656@code{Max_Protected_Entries => 1} 6657 6658@item 6659@code{Max_Task_Entries => 0} 6660 6661No rendezvous statements are allowed. 6662 6663@item 6664@code{No_Abort_Statements} 6665 6666@item 6667@code{No_Dynamic_Attachment} 6668 6669@item 6670@code{No_Dynamic_Priorities} 6671 6672@item 6673@code{No_Implicit_Heap_Allocations} 6674 6675@item 6676@code{No_Local_Protected_Objects} 6677 6678@item 6679@code{No_Local_Timing_Events} 6680 6681@item 6682@code{No_Protected_Type_Allocators} 6683 6684@item 6685@code{No_Relative_Delay} 6686 6687@item 6688@code{No_Requeue_Statements} 6689 6690@item 6691@code{No_Select_Statements} 6692 6693@item 6694@code{No_Specific_Termination_Handlers} 6695 6696@item 6697@code{No_Task_Allocators} 6698 6699@item 6700@code{No_Task_Hierarchy} 6701 6702@item 6703@code{No_Task_Termination} 6704 6705@item 6706@code{Simple_Barriers} 6707@end itemize 6708 6709The Ravenscar profile also includes the following restrictions that specify 6710that there are no semantic dependences on the corresponding predefined 6711packages: 6712 6713 6714@itemize * 6715 6716@item 6717@code{No_Dependence => Ada.Asynchronous_Task_Control} 6718 6719@item 6720@code{No_Dependence => Ada.Calendar} 6721 6722@item 6723@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6724 6725@item 6726@code{No_Dependence => Ada.Execution_Time.Timers} 6727 6728@item 6729@code{No_Dependence => Ada.Task_Attributes} 6730 6731@item 6732@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6733@end itemize 6734 6735This set of configuration pragmas and restrictions correspond to the 6736definition of the 'Ravenscar Profile' for limited tasking, devised and 6737published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6738A description is also available at 6739@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6740 6741The original definition of the profile was revised at subsequent IRTAW 6742meetings. It has been included in the ISO 6743@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6744and was made part of the Ada 2005 standard. 6745The formal definition given by 6746the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6747AI-305) available at 6748@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6749@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6750 6751The above set is a superset of the restrictions provided by pragma 6752@code{Profile (Restricted)}, it includes six additional restrictions 6753(@code{Simple_Barriers}, @code{No_Select_Statements}, 6754@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6755@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6756that pragma @code{Profile (Ravenscar)}, like the pragma 6757@code{Profile (Restricted)}, 6758automatically causes the use of a simplified, 6759more efficient version of the tasking run-time library. 6760 6761@item 6762Pragma Profile (GNAT_Extended_Ravenscar) 6763 6764This profile corresponds to a GNAT specific extension of the 6765Ravenscar profile. The profile may change in the future although 6766only in a compatible way: some restrictions may be removed or 6767relaxed. It is defined as a variation of the Ravenscar profile. 6768 6769The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6770by @code{No_Implicit_Task_Allocations} and 6771@code{No_Implicit_Protected_Object_Allocations}. 6772 6773The @code{Simple_Barriers} restriction has been replaced by 6774@code{Pure_Barriers}. 6775 6776The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and 6777@code{No_Relative_Delay} restrictions have been removed. 6778 6779@item 6780Pragma Profile (GNAT_Ravenscar_EDF) 6781 6782This profile corresponds to the Ravenscar profile but using 6783EDF_Across_Priority as the Task_Scheduling_Policy. 6784 6785@item 6786Pragma Profile (Restricted) 6787 6788This profile corresponds to the GNAT restricted run time. It 6789establishes the following set of restrictions: 6790 6791 6792@itemize * 6793 6794@item 6795@code{No_Abort_Statements} 6796 6797@item 6798@code{No_Entry_Queue} 6799 6800@item 6801@code{No_Task_Hierarchy} 6802 6803@item 6804@code{No_Task_Allocators} 6805 6806@item 6807@code{No_Dynamic_Priorities} 6808 6809@item 6810@code{No_Terminate_Alternatives} 6811 6812@item 6813@code{No_Dynamic_Attachment} 6814 6815@item 6816@code{No_Protected_Type_Allocators} 6817 6818@item 6819@code{No_Local_Protected_Objects} 6820 6821@item 6822@code{No_Requeue_Statements} 6823 6824@item 6825@code{No_Task_Attributes_Package} 6826 6827@item 6828@code{Max_Asynchronous_Select_Nesting = 0} 6829 6830@item 6831@code{Max_Task_Entries = 0} 6832 6833@item 6834@code{Max_Protected_Entries = 1} 6835 6836@item 6837@code{Max_Select_Alternatives = 0} 6838@end itemize 6839 6840This set of restrictions causes the automatic selection of a simplified 6841version of the run time that provides improved performance for the 6842limited set of tasking functionality permitted by this set of restrictions. 6843 6844@item 6845Pragma Profile (Rational) 6846 6847The Rational profile is intended to facilitate porting legacy code that 6848compiles with the Rational APEX compiler, even when the code includes non- 6849conforming Ada constructs. The profile enables the following three pragmas: 6850 6851 6852@itemize * 6853 6854@item 6855@code{pragma Implicit_Packing} 6856 6857@item 6858@code{pragma Overriding_Renamings} 6859 6860@item 6861@code{pragma Use_VADS_Size} 6862@end itemize 6863@end itemize 6864 6865@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6866@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c8} 6867@section Pragma Profile_Warnings 6868 6869 6870Syntax: 6871 6872@example 6873pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6874@end example 6875 6876This is an implementation-defined pragma that is similar in 6877effect to @code{pragma Profile} except that instead of 6878generating @code{Restrictions} pragmas, it generates 6879@code{Restriction_Warnings} pragmas. The result is that 6880violations of the profile generate warning messages instead 6881of error messages. 6882 6883@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 6884@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c9} 6885@section Pragma Propagate_Exceptions 6886 6887 6888@geindex Interfacing to C++ 6889 6890Syntax: 6891 6892@example 6893pragma Propagate_Exceptions; 6894@end example 6895 6896This pragma is now obsolete and, other than generating a warning if warnings 6897on obsolescent features are enabled, is ignored. 6898It is retained for compatibility 6899purposes. It used to be used in connection with optimization of 6900a now-obsolete mechanism for implementation of exceptions. 6901 6902@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 6903@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{ca} 6904@section Pragma Provide_Shift_Operators 6905 6906 6907@geindex Shift operators 6908 6909Syntax: 6910 6911@example 6912pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 6913@end example 6914 6915This pragma can be applied to a first subtype local name that specifies 6916either an unsigned or signed type. It has the effect of providing the 6917five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 6918Rotate_Left and Rotate_Right) for the given type. It is similar to 6919including the function declarations for these five operators, together 6920with the pragma Import (Intrinsic, ...) statements. 6921 6922@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 6923@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{cb} 6924@section Pragma Psect_Object 6925 6926 6927Syntax: 6928 6929@example 6930pragma Psect_Object ( 6931 [Internal =>] LOCAL_NAME, 6932 [, [External =>] EXTERNAL_SYMBOL] 6933 [, [Size =>] EXTERNAL_SYMBOL]); 6934 6935EXTERNAL_SYMBOL ::= 6936 IDENTIFIER 6937| static_string_EXPRESSION 6938@end example 6939 6940This pragma is identical in effect to pragma @code{Common_Object}. 6941 6942@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 6943@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{cd} 6944@section Pragma Pure_Function 6945 6946 6947Syntax: 6948 6949@example 6950pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 6951@end example 6952 6953This pragma appears in the same declarative part as a function 6954declaration (or a set of function declarations if more than one 6955overloaded declaration exists, in which case the pragma applies 6956to all entities). It specifies that the function @code{Entity} is 6957to be considered pure for the purposes of code generation. This means 6958that the compiler can assume that there are no side effects, and 6959in particular that two calls with identical arguments produce the 6960same result. It also means that the function can be used in an 6961address clause. 6962 6963Note that, quite deliberately, there are no static checks to try 6964to ensure that this promise is met, so @code{Pure_Function} can be used 6965with functions that are conceptually pure, even if they do modify 6966global variables. For example, a square root function that is 6967instrumented to count the number of times it is called is still 6968conceptually pure, and can still be optimized, even though it 6969modifies a global variable (the count). Memo functions are another 6970example (where a table of previous calls is kept and consulted to 6971avoid re-computation). 6972 6973Note also that the normal rules excluding optimization of subprograms 6974in pure units (when parameter types are descended from System.Address, 6975or when the full view of a parameter type is limited), do not apply 6976for the Pure_Function case. If you explicitly specify Pure_Function, 6977the compiler may optimize away calls with identical arguments, and 6978if that results in unexpected behavior, the proper action is not to 6979use the pragma for subprograms that are not (conceptually) pure. 6980 6981Note: Most functions in a @code{Pure} package are automatically pure, and 6982there is no need to use pragma @code{Pure_Function} for such functions. One 6983exception is any function that has at least one formal of type 6984@code{System.Address} or a type derived from it. Such functions are not 6985considered pure by default, since the compiler assumes that the 6986@code{Address} parameter may be functioning as a pointer and that the 6987referenced data may change even if the address value does not. 6988Similarly, imported functions are not considered to be pure by default, 6989since there is no way of checking that they are in fact pure. The use 6990of pragma @code{Pure_Function} for such a function will override these default 6991assumption, and cause the compiler to treat a designated subprogram as pure 6992in these cases. 6993 6994Note: If pragma @code{Pure_Function} is applied to a renamed function, it 6995applies to the underlying renamed function. This can be used to 6996disambiguate cases of overloading where some but not all functions 6997in a set of overloaded functions are to be designated as pure. 6998 6999If pragma @code{Pure_Function} is applied to a library-level function, the 7000function is also considered pure from an optimization point of view, but the 7001unit is not a Pure unit in the categorization sense. So for example, a function 7002thus marked is free to @code{with} non-pure units. 7003 7004@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 7005@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ce} 7006@section Pragma Rational 7007 7008 7009Syntax: 7010 7011@example 7012pragma Rational; 7013@end example 7014 7015This pragma is considered obsolescent, but is retained for 7016compatibility purposes. It is equivalent to: 7017 7018@example 7019pragma Profile (Rational); 7020@end example 7021 7022@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 7023@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cf} 7024@section Pragma Ravenscar 7025 7026 7027Syntax: 7028 7029@example 7030pragma Ravenscar; 7031@end example 7032 7033This pragma is considered obsolescent, but is retained for 7034compatibility purposes. It is equivalent to: 7035 7036@example 7037pragma Profile (Ravenscar); 7038@end example 7039 7040which is the preferred method of setting the @code{Ravenscar} profile. 7041 7042@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 7043@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{d1} 7044@section Pragma Refined_Depends 7045 7046 7047Syntax: 7048 7049@example 7050pragma Refined_Depends (DEPENDENCY_RELATION); 7051 7052DEPENDENCY_RELATION ::= 7053 null 7054 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 7055 7056DEPENDENCY_CLAUSE ::= 7057 OUTPUT_LIST =>[+] INPUT_LIST 7058 | NULL_DEPENDENCY_CLAUSE 7059 7060NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 7061 7062OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 7063 7064INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 7065 7066OUTPUT ::= NAME | FUNCTION_RESULT 7067INPUT ::= NAME 7068 7069where FUNCTION_RESULT is a function Result attribute_reference 7070@end example 7071 7072For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in 7073the SPARK 2014 Reference Manual, section 6.1.5. 7074 7075@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 7076@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{d3} 7077@section Pragma Refined_Global 7078 7079 7080Syntax: 7081 7082@example 7083pragma Refined_Global (GLOBAL_SPECIFICATION); 7084 7085GLOBAL_SPECIFICATION ::= 7086 null 7087 | (GLOBAL_LIST) 7088 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 7089 7090MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 7091 7092MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 7093GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 7094GLOBAL_ITEM ::= NAME 7095@end example 7096 7097For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in 7098the SPARK 2014 Reference Manual, section 6.1.4. 7099 7100@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 7101@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d4}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d5} 7102@section Pragma Refined_Post 7103 7104 7105Syntax: 7106 7107@example 7108pragma Refined_Post (boolean_EXPRESSION); 7109@end example 7110 7111For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in 7112the SPARK 2014 Reference Manual, section 7.2.7. 7113 7114@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 7115@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d6}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d7} 7116@section Pragma Refined_State 7117 7118 7119Syntax: 7120 7121@example 7122pragma Refined_State (REFINEMENT_LIST); 7123 7124REFINEMENT_LIST ::= 7125 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 7126 7127REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 7128 7129CONSTITUENT_LIST ::= 7130 null 7131 | CONSTITUENT 7132 | (CONSTITUENT @{, CONSTITUENT@}) 7133 7134CONSTITUENT ::= object_NAME | state_NAME 7135@end example 7136 7137For the semantics of this pragma, see the entry for aspect @code{Refined_State} in 7138the SPARK 2014 Reference Manual, section 7.2.2. 7139 7140@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 7141@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d8} 7142@section Pragma Relative_Deadline 7143 7144 7145Syntax: 7146 7147@example 7148pragma Relative_Deadline (time_span_EXPRESSION); 7149@end example 7150 7151This pragma is standard in Ada 2005, but is available in all earlier 7152versions of Ada as an implementation-defined pragma. 7153See Ada 2012 Reference Manual for details. 7154 7155@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas 7156@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d9}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{da} 7157@section Pragma Remote_Access_Type 7158 7159 7160Syntax: 7161 7162@example 7163pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 7164@end example 7165 7166This pragma appears in the formal part of a generic declaration. 7167It specifies an exception to the RM rule from E.2.2(17/2), which forbids 7168the use of a remote access to class-wide type as actual for a formal 7169access type. 7170 7171When this pragma applies to a formal access type @code{Entity}, that 7172type is treated as a remote access to class-wide type in the generic. 7173It must be a formal general access type, and its designated type must 7174be the class-wide type of a formal tagged limited private type from the 7175same generic declaration. 7176 7177In the generic unit, the formal type is subject to all restrictions 7178pertaining to remote access to class-wide types. At instantiation, the 7179actual type must be a remote access to class-wide type. 7180 7181@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas 7182@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{db} 7183@section Pragma Restricted_Run_Time 7184 7185 7186Syntax: 7187 7188@example 7189pragma Restricted_Run_Time; 7190@end example 7191 7192This pragma is considered obsolescent, but is retained for 7193compatibility purposes. It is equivalent to: 7194 7195@example 7196pragma Profile (Restricted); 7197@end example 7198 7199which is the preferred method of setting the restricted run time 7200profile. 7201 7202@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 7203@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{dc} 7204@section Pragma Restriction_Warnings 7205 7206 7207Syntax: 7208 7209@example 7210pragma Restriction_Warnings 7211 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 7212@end example 7213 7214This pragma allows a series of restriction identifiers to be 7215specified (the list of allowed identifiers is the same as for 7216pragma @code{Restrictions}). For each of these identifiers 7217the compiler checks for violations of the restriction, but 7218generates a warning message rather than an error message 7219if the restriction is violated. 7220 7221One use of this is in situations where you want to know 7222about violations of a restriction, but you want to ignore some of 7223these violations. Consider this example, where you want to set 7224Ada_95 mode and enable style checks, but you want to know about 7225any other use of implementation pragmas: 7226 7227@example 7228pragma Restriction_Warnings (No_Implementation_Pragmas); 7229pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 7230pragma Ada_95; 7231pragma Style_Checks ("2bfhkM160"); 7232pragma Warnings (On, "violation of No_Implementation_Pragmas"); 7233@end example 7234 7235By including the above lines in a configuration pragmas file, 7236the Ada_95 and Style_Checks pragmas are accepted without 7237generating a warning, but any other use of implementation 7238defined pragmas will cause a warning to be generated. 7239 7240@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas 7241@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{dd} 7242@section Pragma Reviewable 7243 7244 7245Syntax: 7246 7247@example 7248pragma Reviewable; 7249@end example 7250 7251This pragma is an RM-defined standard pragma, but has no effect on the 7252program being compiled, or on the code generated for the program. 7253 7254To obtain the required output specified in RM H.3.1, the compiler must be 7255run with various special switches as follows: 7256 7257 7258@itemize * 7259 7260@item 7261@emph{Where compiler-generated run-time checks remain} 7262 7263The switch @emph{-gnatGL} 7264may be used to list the expanded code in pseudo-Ada form. 7265Runtime checks show up in the listing either as explicit 7266checks or operators marked with @{@} to indicate a check is present. 7267 7268@item 7269@emph{An identification of known exceptions at compile time} 7270 7271If the program is compiled with @emph{-gnatwa}, 7272the compiler warning messages will indicate all cases where the compiler 7273detects that an exception is certain to occur at run time. 7274 7275@item 7276@emph{Possible reads of uninitialized variables} 7277 7278The compiler warns of many such cases, but its output is incomplete. 7279@end itemize 7280 7281 7282A supplemental static analysis tool 7283may be used to obtain a comprehensive list of all 7284possible points at which uninitialized data may be read. 7285 7286 7287@itemize * 7288 7289@item 7290@emph{Where run-time support routines are implicitly invoked} 7291 7292In the output from @emph{-gnatGL}, 7293run-time calls are explicitly listed as calls to the relevant 7294run-time routine. 7295 7296@item 7297@emph{Object code listing} 7298 7299This may be obtained either by using the @emph{-S} switch, 7300or the objdump utility. 7301 7302@item 7303@emph{Constructs known to be erroneous at compile time} 7304 7305These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 7306 7307@item 7308@emph{Stack usage information} 7309 7310Static stack usage data (maximum per-subprogram) can be obtained via the 7311@emph{-fstack-usage} switch to the compiler. 7312Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 7313to gnatbind 7314@end itemize 7315 7316 7317 7318@itemize * 7319 7320@item 7321@emph{Object code listing of entire partition} 7322 7323This can be obtained by compiling the partition with @emph{-S}, 7324or by applying objdump 7325to all the object files that are part of the partition. 7326 7327@item 7328@emph{A description of the run-time model} 7329 7330The full sources of the run-time are available, and the documentation of 7331these routines describes how these run-time routines interface to the 7332underlying operating system facilities. 7333 7334@item 7335@emph{Control and data-flow information} 7336@end itemize 7337 7338 7339A supplemental static analysis tool 7340may be used to obtain complete control and data-flow information, as well as 7341comprehensive messages identifying possible problems based on this 7342information. 7343 7344@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas 7345@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{df} 7346@section Pragma Secondary_Stack_Size 7347 7348 7349Syntax: 7350 7351@example 7352pragma Secondary_Stack_Size (integer_EXPRESSION); 7353@end example 7354 7355This pragma appears within the task definition of a single task declaration 7356or a task type declaration (like pragma @code{Storage_Size}) and applies to all 7357task objects of that type. The argument specifies the size of the secondary 7358stack to be used by these task objects, and must be of an integer type. The 7359secondary stack is used to handle functions that return a variable-sized 7360result, for example a function returning an unconstrained String. 7361 7362Note this pragma only applies to targets using fixed secondary stacks, like 7363VxWorks 653 and bare board targets, where a fixed block for the 7364secondary stack is allocated from the primary stack of the task. By default, 7365these targets assign a percentage of the primary stack for the secondary stack, 7366as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, 7367an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. 7368 7369For most targets, the pragma does not apply as the secondary stack grows on 7370demand: allocated as a chain of blocks in the heap. The default size of these 7371blocks can be modified via the @code{-D} binder option as described in 7372@cite{GNAT User's Guide}. 7373 7374Note that no check is made to see if the secondary stack can fit inside the 7375primary stack. 7376 7377Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} 7378is in effect. 7379 7380@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas 7381@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e0} 7382@section Pragma Share_Generic 7383 7384 7385Syntax: 7386 7387@example 7388pragma Share_Generic (GNAME @{, GNAME@}); 7389 7390GNAME ::= generic_unit_NAME | generic_instance_NAME 7391@end example 7392 7393This pragma is provided for compatibility with Dec Ada 83. It has 7394no effect in GNAT (which does not implement shared generics), other 7395than to check that the given names are all names of generic units or 7396generic instances. 7397 7398@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 7399@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e2} 7400@section Pragma Shared 7401 7402 7403This pragma is provided for compatibility with Ada 83. The syntax and 7404semantics are identical to pragma Atomic. 7405 7406@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 7407@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e3} 7408@section Pragma Short_Circuit_And_Or 7409 7410 7411Syntax: 7412 7413@example 7414pragma Short_Circuit_And_Or; 7415@end example 7416 7417This configuration pragma causes any occurrence of the AND operator applied to 7418operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 7419is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 7420may be useful in the context of certification protocols requiring the use of 7421short-circuited logical operators. If this configuration pragma occurs locally 7422within the file being compiled, it applies only to the file being compiled. 7423There is no requirement that all units in a partition use this option. 7424 7425@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 7426@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e4} 7427@section Pragma Short_Descriptors 7428 7429 7430Syntax: 7431 7432@example 7433pragma Short_Descriptors 7434@end example 7435 7436This pragma is provided for compatibility with other Ada implementations. It 7437is recognized but ignored by all current versions of GNAT. 7438 7439@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 7440@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e6} 7441@section Pragma Simple_Storage_Pool_Type 7442 7443 7444@geindex Storage pool 7445@geindex simple 7446 7447@geindex Simple storage pool 7448 7449Syntax: 7450 7451@example 7452pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 7453@end example 7454 7455A type can be established as a 'simple storage pool type' by applying 7456the representation pragma @code{Simple_Storage_Pool_Type} to the type. 7457A type named in the pragma must be a library-level immutably limited record 7458type or limited tagged type declared immediately within a package declaration. 7459The type can also be a limited private type whose full type is allowed as 7460a simple storage pool type. 7461 7462For a simple storage pool type @code{SSP}, nonabstract primitive subprograms 7463@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 7464are subtype conformant with the following subprogram declarations: 7465 7466@example 7467procedure Allocate 7468 (Pool : in out SSP; 7469 Storage_Address : out System.Address; 7470 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7471 Alignment : System.Storage_Elements.Storage_Count); 7472 7473procedure Deallocate 7474 (Pool : in out SSP; 7475 Storage_Address : System.Address; 7476 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7477 Alignment : System.Storage_Elements.Storage_Count); 7478 7479function Storage_Size (Pool : SSP) 7480 return System.Storage_Elements.Storage_Count; 7481@end example 7482 7483Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 7484@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 7485applying an unchecked deallocation has no effect other than to set its actual 7486parameter to null. If @code{Storage_Size} is not declared, then the 7487@code{Storage_Size} attribute applied to an access type associated with 7488a pool object of type SSP returns zero. Additional operations can be declared 7489for a simple storage pool type (such as for supporting a mark/release 7490storage-management discipline). 7491 7492An object of a simple storage pool type can be associated with an access 7493type by specifying the attribute 7494@ref{e7,,Simple_Storage_Pool}. For example: 7495 7496@example 7497My_Pool : My_Simple_Storage_Pool_Type; 7498 7499type Acc is access My_Data_Type; 7500 7501for Acc'Simple_Storage_Pool use My_Pool; 7502@end example 7503 7504See attribute @ref{e7,,Simple_Storage_Pool} 7505for further details. 7506 7507@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7508@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e9} 7509@section Pragma Source_File_Name 7510 7511 7512Syntax: 7513 7514@example 7515pragma Source_File_Name ( 7516 [Unit_Name =>] unit_NAME, 7517 Spec_File_Name => STRING_LITERAL, 7518 [Index => INTEGER_LITERAL]); 7519 7520pragma Source_File_Name ( 7521 [Unit_Name =>] unit_NAME, 7522 Body_File_Name => STRING_LITERAL, 7523 [Index => INTEGER_LITERAL]); 7524@end example 7525 7526Use this to override the normal naming convention. It is a configuration 7527pragma, and so has the usual applicability of configuration pragmas 7528(i.e., it applies to either an entire partition, or to all units in a 7529compilation, or to a single unit, depending on how it is used. 7530@code{unit_name} is mapped to @code{file_name_literal}. The identifier for 7531the second argument is required, and indicates whether this is the file 7532name for the spec or for the body. 7533 7534The optional Index argument should be used when a file contains multiple 7535units, and when you do not want to use @code{gnatchop} to separate then 7536into multiple files (which is the recommended procedure to limit the 7537number of recompilations that are needed when some sources change). 7538For instance, if the source file @code{source.ada} contains 7539 7540@example 7541package B is 7542... 7543end B; 7544 7545with B; 7546procedure A is 7547begin 7548 .. 7549end A; 7550@end example 7551 7552you could use the following configuration pragmas: 7553 7554@example 7555pragma Source_File_Name 7556 (B, Spec_File_Name => "source.ada", Index => 1); 7557pragma Source_File_Name 7558 (A, Body_File_Name => "source.ada", Index => 2); 7559@end example 7560 7561Note that the @code{gnatname} utility can also be used to generate those 7562configuration pragmas. 7563 7564Another form of the @code{Source_File_Name} pragma allows 7565the specification of patterns defining alternative file naming schemes 7566to apply to all files. 7567 7568@example 7569pragma Source_File_Name 7570 ( [Spec_File_Name =>] STRING_LITERAL 7571 [,[Casing =>] CASING_SPEC] 7572 [,[Dot_Replacement =>] STRING_LITERAL]); 7573 7574pragma Source_File_Name 7575 ( [Body_File_Name =>] STRING_LITERAL 7576 [,[Casing =>] CASING_SPEC] 7577 [,[Dot_Replacement =>] STRING_LITERAL]); 7578 7579pragma Source_File_Name 7580 ( [Subunit_File_Name =>] STRING_LITERAL 7581 [,[Casing =>] CASING_SPEC] 7582 [,[Dot_Replacement =>] STRING_LITERAL]); 7583 7584CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7585@end example 7586 7587The first argument is a pattern that contains a single asterisk indicating 7588the point at which the unit name is to be inserted in the pattern string 7589to form the file name. The second argument is optional. If present it 7590specifies the casing of the unit name in the resulting file name string. 7591The default is lower case. Finally the third argument allows for systematic 7592replacement of any dots in the unit name by the specified string literal. 7593 7594Note that Source_File_Name pragmas should not be used if you are using 7595project files. The reason for this rule is that the project manager is not 7596aware of these pragmas, and so other tools that use the projet file would not 7597be aware of the intended naming conventions. If you are using project files, 7598file naming is controlled by Source_File_Name_Project pragmas, which are 7599usually supplied automatically by the project manager. A pragma 7600Source_File_Name cannot appear after a @ref{ea,,Pragma Source_File_Name_Project}. 7601 7602For more details on the use of the @code{Source_File_Name} pragma, see the 7603sections on @code{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}. 7604 7605@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7606@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{eb} 7607@section Pragma Source_File_Name_Project 7608 7609 7610This pragma has the same syntax and semantics as pragma Source_File_Name. 7611It is only allowed as a stand-alone configuration pragma. 7612It cannot appear after a @ref{e8,,Pragma Source_File_Name}, and 7613most importantly, once pragma Source_File_Name_Project appears, 7614no further Source_File_Name pragmas are allowed. 7615 7616The intention is that Source_File_Name_Project pragmas are always 7617generated by the Project Manager in a manner consistent with the naming 7618specified in a project file, and when naming is controlled in this manner, 7619it is not permissible to attempt to modify this naming scheme using 7620Source_File_Name or Source_File_Name_Project pragmas (which would not be 7621known to the project manager). 7622 7623@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7624@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ec} 7625@section Pragma Source_Reference 7626 7627 7628Syntax: 7629 7630@example 7631pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7632@end example 7633 7634This pragma must appear as the first line of a source file. 7635@code{integer_literal} is the logical line number of the line following 7636the pragma line (for use in error messages and debugging 7637information). @code{string_literal} is a static string constant that 7638specifies the file name to be used in error messages and debugging 7639information. This is most notably used for the output of @code{gnatchop} 7640with the @emph{-r} switch, to make sure that the original unchopped 7641source file is the one referred to. 7642 7643The second argument must be a string literal, it cannot be a static 7644string expression other than a string literal. This is because its value 7645is needed for error messages issued by all phases of the compiler. 7646 7647@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7648@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ed}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{ee} 7649@section Pragma SPARK_Mode 7650 7651 7652Syntax: 7653 7654@example 7655pragma SPARK_Mode [(On | Off)] ; 7656@end example 7657 7658In general a program can have some parts that are in SPARK 2014 (and 7659follow all the rules in the SPARK Reference Manual), and some parts 7660that are full Ada 2012. 7661 7662The SPARK_Mode pragma is used to identify which parts are in SPARK 76632014 (by default programs are in full Ada). The SPARK_Mode pragma can 7664be used in the following places: 7665 7666 7667@itemize * 7668 7669@item 7670As a configuration pragma, in which case it sets the default mode for 7671all units compiled with this pragma. 7672 7673@item 7674Immediately following a library-level subprogram spec 7675 7676@item 7677Immediately within a library-level package body 7678 7679@item 7680Immediately following the @code{private} keyword of a library-level 7681package spec 7682 7683@item 7684Immediately following the @code{begin} keyword of a library-level 7685package body 7686 7687@item 7688Immediately within a library-level subprogram body 7689@end itemize 7690 7691Normally a subprogram or package spec/body inherits the current mode 7692that is active at the point it is declared. But this can be overridden 7693by pragma within the spec or body as above. 7694 7695The basic consistency rule is that you can't turn SPARK_Mode back 7696@code{On}, once you have explicitly (with a pragma) turned if 7697@code{Off}. So the following rules apply: 7698 7699If a subprogram spec has SPARK_Mode @code{Off}, then the body must 7700also have SPARK_Mode @code{Off}. 7701 7702For a package, we have four parts: 7703 7704 7705@itemize * 7706 7707@item 7708the package public declarations 7709 7710@item 7711the package private part 7712 7713@item 7714the body of the package 7715 7716@item 7717the elaboration code after @code{begin} 7718@end itemize 7719 7720For a package, the rule is that if you explicitly turn SPARK_Mode 7721@code{Off} for any part, then all the following parts must have 7722SPARK_Mode @code{Off}. Note that this may require repeating a pragma 7723SPARK_Mode (@code{Off}) in the body. For example, if we have a 7724configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 7725default everywhere, and one particular package spec has pragma 7726SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 7727the package body. 7728 7729@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7730@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ef} 7731@section Pragma Static_Elaboration_Desired 7732 7733 7734Syntax: 7735 7736@example 7737pragma Static_Elaboration_Desired; 7738@end example 7739 7740This pragma is used to indicate that the compiler should attempt to initialize 7741statically the objects declared in the library unit to which the pragma applies, 7742when these objects are initialized (explicitly or implicitly) by an aggregate. 7743In the absence of this pragma, aggregates in object declarations are expanded 7744into assignments and loops, even when the aggregate components are static 7745constants. When the aggregate is present the compiler builds a static expression 7746that requires no run-time code, so that the initialized object can be placed in 7747read-only data space. If the components are not static, or the aggregate has 7748more that 100 components, the compiler emits a warning that the pragma cannot 7749be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7750construction of larger aggregates with static components that include an others 7751choice.) 7752 7753@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7754@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f0} 7755@section Pragma Stream_Convert 7756 7757 7758Syntax: 7759 7760@example 7761pragma Stream_Convert ( 7762 [Entity =>] type_LOCAL_NAME, 7763 [Read =>] function_NAME, 7764 [Write =>] function_NAME); 7765@end example 7766 7767This pragma provides an efficient way of providing user-defined stream 7768attributes. Not only is it simpler to use than specifying the attributes 7769directly, but more importantly, it allows the specification to be made in such 7770a way that the predefined unit Ada.Streams is not loaded unless it is actually 7771needed (i.e. unless the stream attributes are actually used); the use of 7772the Stream_Convert pragma adds no overhead at all, unless the stream 7773attributes are actually used on the designated type. 7774 7775The first argument specifies the type for which stream functions are 7776provided. The second parameter provides a function used to read values 7777of this type. It must name a function whose argument type may be any 7778subtype, and whose returned type must be the type given as the first 7779argument to the pragma. 7780 7781The meaning of the @code{Read} parameter is that if a stream attribute directly 7782or indirectly specifies reading of the type given as the first parameter, 7783then a value of the type given as the argument to the Read function is 7784read from the stream, and then the Read function is used to convert this 7785to the required target type. 7786 7787Similarly the @code{Write} parameter specifies how to treat write attributes 7788that directly or indirectly apply to the type given as the first parameter. 7789It must have an input parameter of the type specified by the first parameter, 7790and the return type must be the same as the input type of the Read function. 7791The effect is to first call the Write function to convert to the given stream 7792type, and then write the result type to the stream. 7793 7794The Read and Write functions must not be overloaded subprograms. If necessary 7795renamings can be supplied to meet this requirement. 7796The usage of this attribute is best illustrated by a simple example, taken 7797from the GNAT implementation of package Ada.Strings.Unbounded: 7798 7799@example 7800function To_Unbounded (S : String) return Unbounded_String 7801 renames To_Unbounded_String; 7802 7803pragma Stream_Convert 7804 (Unbounded_String, To_Unbounded, To_String); 7805@end example 7806 7807The specifications of the referenced functions, as given in the Ada 7808Reference Manual are: 7809 7810@example 7811function To_Unbounded_String (Source : String) 7812 return Unbounded_String; 7813 7814function To_String (Source : Unbounded_String) 7815 return String; 7816@end example 7817 7818The effect is that if the value of an unbounded string is written to a stream, 7819then the representation of the item in the stream is in the same format that 7820would be used for @code{Standard.String'Output}, and this same representation 7821is expected when a value of this type is read from the stream. Note that the 7822value written always includes the bounds, even for Unbounded_String'Write, 7823since Unbounded_String is not an array type. 7824 7825Note that the @code{Stream_Convert} pragma is not effective in the case of 7826a derived type of a non-limited tagged type. If such a type is specified then 7827the pragma is silently ignored, and the default implementation of the stream 7828attributes is used instead. 7829 7830@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7831@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f1} 7832@section Pragma Style_Checks 7833 7834 7835Syntax: 7836 7837@example 7838pragma Style_Checks (string_LITERAL | ALL_CHECKS | 7839 On | Off [, LOCAL_NAME]); 7840@end example 7841 7842This pragma is used in conjunction with compiler switches to control the 7843built in style checking provided by GNAT. The compiler switches, if set, 7844provide an initial setting for the switches, and this pragma may be used 7845to modify these settings, or the settings may be provided entirely by 7846the use of the pragma. This pragma can be used anywhere that a pragma 7847is legal, including use as a configuration pragma (including use in 7848the @code{gnat.adc} file). 7849 7850The form with a string literal specifies which style options are to be 7851activated. These are additive, so they apply in addition to any previously 7852set style check options. The codes for the options are the same as those 7853used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 7854For example the following two methods can be used to enable 7855layout checking: 7856 7857 7858@itemize * 7859 7860@item 7861@example 7862pragma Style_Checks ("l"); 7863@end example 7864 7865@item 7866@example 7867gcc -c -gnatyl ... 7868@end example 7869@end itemize 7870 7871The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent 7872to the use of the @code{gnaty} switch with no options. 7873See the @cite{GNAT User's Guide} for details.) 7874 7875Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). 7876In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check 7877options (i.e. equivalent to @code{-gnatyg}). 7878 7879The forms with @code{Off} and @code{On} 7880can be used to temporarily disable style checks 7881as shown in the following example: 7882 7883@example 7884pragma Style_Checks ("k"); -- requires keywords in lower case 7885pragma Style_Checks (Off); -- turn off style checks 7886NULL; -- this will not generate an error message 7887pragma Style_Checks (On); -- turn style checks back on 7888NULL; -- this will generate an error message 7889@end example 7890 7891Finally the two argument form is allowed only if the first argument is 7892@code{On} or @code{Off}. The effect is to turn of semantic style checks 7893for the specified entity, as shown in the following example: 7894 7895@example 7896pragma Style_Checks ("r"); -- require consistency of identifier casing 7897Arg : Integer; 7898Rf1 : Integer := ARG; -- incorrect, wrong case 7899pragma Style_Checks (Off, Arg); 7900Rf2 : Integer := ARG; -- OK, no error 7901@end example 7902 7903@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 7904@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f2} 7905@section Pragma Subtitle 7906 7907 7908Syntax: 7909 7910@example 7911pragma Subtitle ([Subtitle =>] STRING_LITERAL); 7912@end example 7913 7914This pragma is recognized for compatibility with other Ada compilers 7915but is ignored by GNAT. 7916 7917@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 7918@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f3} 7919@section Pragma Suppress 7920 7921 7922Syntax: 7923 7924@example 7925pragma Suppress (Identifier [, [On =>] Name]); 7926@end example 7927 7928This is a standard pragma, and supports all the check names required in 7929the RM. It is included here because GNAT recognizes some additional check 7930names that are implementation defined (as permitted by the RM): 7931 7932 7933@itemize * 7934 7935@item 7936@code{Alignment_Check} can be used to suppress alignment checks 7937on addresses used in address clauses. Such checks can also be suppressed 7938by suppressing range checks, but the specific use of @code{Alignment_Check} 7939allows suppression of alignment checks without suppressing other range checks. 7940Note that @code{Alignment_Check} is suppressed by default on machines (such as 7941the x86) with non-strict alignment. 7942 7943@item 7944@code{Atomic_Synchronization} can be used to suppress the special memory 7945synchronization instructions that are normally generated for access to 7946@code{Atomic} variables to ensure correct synchronization between tasks 7947that use such variables for synchronization purposes. 7948 7949@item 7950@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated 7951for a duplicated tag value when a tagged type is declared. 7952 7953@item 7954@code{Container_Checks} Can be used to suppress all checks within Ada.Containers 7955and instances of its children, including Tampering_Check. 7956 7957@item 7958@code{Tampering_Check} Can be used to suppress tampering check in the containers. 7959 7960@item 7961@code{Predicate_Check} can be used to control whether predicate checks are 7962active. It is applicable only to predicates for which the policy is 7963@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 7964predicate is ignored or checked for the whole program, the use of 7965@code{Suppress} and @code{Unsuppress} with this check name allows a given 7966predicate to be turned on and off at specific points in the program. 7967 7968@item 7969@code{Validity_Check} can be used specifically to control validity checks. 7970If @code{Suppress} is used to suppress validity checks, then no validity 7971checks are performed, including those specified by the appropriate compiler 7972switch or the @code{Validity_Checks} pragma. 7973 7974@item 7975Additional check names previously introduced by use of the @code{Check_Name} 7976pragma are also allowed. 7977@end itemize 7978 7979Note that pragma Suppress gives the compiler permission to omit 7980checks, but does not require the compiler to omit checks. The compiler 7981will generate checks if they are essentially free, even when they are 7982suppressed. In particular, if the compiler can prove that a certain 7983check will necessarily fail, it will generate code to do an 7984unconditional 'raise', even if checks are suppressed. The compiler 7985warns in this case. 7986 7987Of course, run-time checks are omitted whenever the compiler can prove 7988that they will not fail, whether or not checks are suppressed. 7989 7990@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 7991@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f4} 7992@section Pragma Suppress_All 7993 7994 7995Syntax: 7996 7997@example 7998pragma Suppress_All; 7999@end example 8000 8001This pragma can appear anywhere within a unit. 8002The effect is to apply @code{Suppress (All_Checks)} to the unit 8003in which it appears. This pragma is implemented for compatibility with DEC 8004Ada 83 usage where it appears at the end of a unit, and for compatibility 8005with Rational Ada, where it appears as a program unit pragma. 8006The use of the standard Ada pragma @code{Suppress (All_Checks)} 8007as a normal configuration pragma is the preferred usage in GNAT. 8008 8009@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 8010@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f6} 8011@section Pragma Suppress_Debug_Info 8012 8013 8014Syntax: 8015 8016@example 8017pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 8018@end example 8019 8020This pragma can be used to suppress generation of debug information 8021for the specified entity. It is intended primarily for use in debugging 8022the debugger, and navigating around debugger problems. 8023 8024@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 8025@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f7} 8026@section Pragma Suppress_Exception_Locations 8027 8028 8029Syntax: 8030 8031@example 8032pragma Suppress_Exception_Locations; 8033@end example 8034 8035In normal mode, a raise statement for an exception by default generates 8036an exception message giving the file name and line number for the location 8037of the raise. This is useful for debugging and logging purposes, but this 8038entails extra space for the strings for the messages. The configuration 8039pragma @code{Suppress_Exception_Locations} can be used to suppress the 8040generation of these strings, with the result that space is saved, but the 8041exception message for such raises is null. This configuration pragma may 8042appear in a global configuration pragma file, or in a specific unit as 8043usual. It is not required that this pragma be used consistently within 8044a partition, so it is fine to have some units within a partition compiled 8045with this pragma and others compiled in normal mode without it. 8046 8047@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 8048@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f8}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f9} 8049@section Pragma Suppress_Initialization 8050 8051 8052@geindex Suppressing initialization 8053 8054@geindex Initialization 8055@geindex suppression of 8056 8057Syntax: 8058 8059@example 8060pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 8061@end example 8062 8063Here variable_or_subtype_Name is the name introduced by a type declaration 8064or subtype declaration or the name of a variable introduced by an 8065object declaration. 8066 8067In the case of a type or subtype 8068this pragma suppresses any implicit or explicit initialization 8069for all variables of the given type or subtype, 8070including initialization resulting from the use of pragmas 8071Normalize_Scalars or Initialize_Scalars. 8072 8073This is considered a representation item, so it cannot be given after 8074the type is frozen. It applies to all subsequent object declarations, 8075and also any allocator that creates objects of the type. 8076 8077If the pragma is given for the first subtype, then it is considered 8078to apply to the base type and all its subtypes. If the pragma is given 8079for other than a first subtype, then it applies only to the given subtype. 8080The pragma may not be given after the type is frozen. 8081 8082Note that this includes eliminating initialization of discriminants 8083for discriminated types, and tags for tagged types. In these cases, 8084you will have to use some non-portable mechanism (e.g. address 8085overlays or unchecked conversion) to achieve required initialization 8086of these fields before accessing any object of the corresponding type. 8087 8088For the variable case, implicit initialization for the named variable 8089is suppressed, just as though its subtype had been given in a pragma 8090Suppress_Initialization, as described above. 8091 8092@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 8093@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fa} 8094@section Pragma Task_Name 8095 8096 8097Syntax 8098 8099@example 8100pragma Task_Name (string_EXPRESSION); 8101@end example 8102 8103This pragma appears within a task definition (like pragma 8104@code{Priority}) and applies to the task in which it appears. The 8105argument must be of type String, and provides a name to be used for 8106the task instance when the task is created. Note that this expression 8107is not required to be static, and in particular, it can contain 8108references to task discriminants. This facility can be used to 8109provide different names for different tasks as they are created, 8110as illustrated in the example below. 8111 8112The task name is recorded internally in the run-time structures 8113and is accessible to tools like the debugger. In addition the 8114routine @code{Ada.Task_Identification.Image} will return this 8115string, with a unique task address appended. 8116 8117@example 8118-- Example of the use of pragma Task_Name 8119 8120with Ada.Task_Identification; 8121use Ada.Task_Identification; 8122with Text_IO; use Text_IO; 8123procedure t3 is 8124 8125 type Astring is access String; 8126 8127 task type Task_Typ (Name : access String) is 8128 pragma Task_Name (Name.all); 8129 end Task_Typ; 8130 8131 task body Task_Typ is 8132 Nam : constant String := Image (Current_Task); 8133 begin 8134 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 8135 end Task_Typ; 8136 8137 type Ptr_Task is access Task_Typ; 8138 Task_Var : Ptr_Task; 8139 8140begin 8141 Task_Var := 8142 new Task_Typ (new String'("This is task 1")); 8143 Task_Var := 8144 new Task_Typ (new String'("This is task 2")); 8145end; 8146@end example 8147 8148@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 8149@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fb} 8150@section Pragma Task_Storage 8151 8152 8153Syntax: 8154 8155@example 8156pragma Task_Storage ( 8157 [Task_Type =>] LOCAL_NAME, 8158 [Top_Guard =>] static_integer_EXPRESSION); 8159@end example 8160 8161This pragma specifies the length of the guard area for tasks. The guard 8162area is an additional storage area allocated to a task. A value of zero 8163means that either no guard area is created or a minimal guard area is 8164created, depending on the target. This pragma can appear anywhere a 8165@code{Storage_Size} attribute definition clause is allowed for a task 8166type. 8167 8168@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 8169@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{fd} 8170@section Pragma Test_Case 8171 8172 8173@geindex Test cases 8174 8175Syntax: 8176 8177@example 8178pragma Test_Case ( 8179 [Name =>] static_string_Expression 8180 ,[Mode =>] (Nominal | Robustness) 8181 [, Requires => Boolean_Expression] 8182 [, Ensures => Boolean_Expression]); 8183@end example 8184 8185The @code{Test_Case} pragma allows defining fine-grain specifications 8186for use by testing tools. 8187The compiler checks the validity of the @code{Test_Case} pragma, but its 8188presence does not lead to any modification of the code generated by the 8189compiler. 8190 8191@code{Test_Case} pragmas may only appear immediately following the 8192(separate) declaration of a subprogram in a package declaration, inside 8193a package spec unit. Only other pragmas may intervene (that is appear 8194between the subprogram declaration and a test case). 8195 8196The compiler checks that boolean expressions given in @code{Requires} and 8197@code{Ensures} are valid, where the rules for @code{Requires} are the 8198same as the rule for an expression in @code{Precondition} and the rules 8199for @code{Ensures} are the same as the rule for an expression in 8200@code{Postcondition}. In particular, attributes @code{'Old} and 8201@code{'Result} can only be used within the @code{Ensures} 8202expression. The following is an example of use within a package spec: 8203 8204@example 8205package Math_Functions is 8206 ... 8207 function Sqrt (Arg : Float) return Float; 8208 pragma Test_Case (Name => "Test 1", 8209 Mode => Nominal, 8210 Requires => Arg < 10000, 8211 Ensures => Sqrt'Result < 10); 8212 ... 8213end Math_Functions; 8214@end example 8215 8216The meaning of a test case is that there is at least one context where 8217@code{Requires} holds such that, if the associated subprogram is executed in 8218that context, then @code{Ensures} holds when the subprogram returns. 8219Mode @code{Nominal} indicates that the input context should also satisfy the 8220precondition of the subprogram, and the output context should also satisfy its 8221postcondition. Mode @code{Robustness} indicates that the precondition and 8222postcondition of the subprogram should be ignored for this test case. 8223 8224@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 8225@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fe}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{ff} 8226@section Pragma Thread_Local_Storage 8227 8228 8229@geindex Task specific storage 8230 8231@geindex TLS (Thread Local Storage) 8232 8233@geindex Task_Attributes 8234 8235Syntax: 8236 8237@example 8238pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 8239@end example 8240 8241This pragma specifies that the specified entity, which must be 8242a variable declared in a library-level package, is to be marked as 8243"Thread Local Storage" (@code{TLS}). On systems supporting this (which 8244include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each 8245thread (and hence each Ada task) to see a distinct copy of the variable. 8246 8247The variable must not have default initialization, and if there is 8248an explicit initialization, it must be either @code{null} for an 8249access variable, a static expression for a scalar variable, or a fully 8250static aggregate for a composite type, that is to say, an aggregate all 8251of whose components are static, and which does not include packed or 8252discriminated components. 8253 8254This provides a low-level mechanism similar to that provided by 8255the @code{Ada.Task_Attributes} package, but much more efficient 8256and is also useful in writing interface code that will interact 8257with foreign threads. 8258 8259If this pragma is used on a system where @code{TLS} is not supported, 8260then an error message will be generated and the program will be rejected. 8261 8262@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 8263@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{100} 8264@section Pragma Time_Slice 8265 8266 8267Syntax: 8268 8269@example 8270pragma Time_Slice (static_duration_EXPRESSION); 8271@end example 8272 8273For implementations of GNAT on operating systems where it is possible 8274to supply a time slice value, this pragma may be used for this purpose. 8275It is ignored if it is used in a system that does not allow this control, 8276or if it appears in other than the main program unit. 8277 8278@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 8279@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{101} 8280@section Pragma Title 8281 8282 8283Syntax: 8284 8285@example 8286pragma Title (TITLING_OPTION [, TITLING OPTION]); 8287 8288TITLING_OPTION ::= 8289 [Title =>] STRING_LITERAL, 8290| [Subtitle =>] STRING_LITERAL 8291@end example 8292 8293Syntax checked but otherwise ignored by GNAT. This is a listing control 8294pragma used in DEC Ada 83 implementations to provide a title and/or 8295subtitle for the program listing. The program listing generated by GNAT 8296does not have titles or subtitles. 8297 8298Unlike other pragmas, the full flexibility of named notation is allowed 8299for this pragma, i.e., the parameters may be given in any order if named 8300notation is used, and named and positional notation can be mixed 8301following the normal rules for procedure calls in Ada. 8302 8303@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 8304@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{102} 8305@section Pragma Type_Invariant 8306 8307 8308Syntax: 8309 8310@example 8311pragma Type_Invariant 8312 ([Entity =>] type_LOCAL_NAME, 8313 [Check =>] EXPRESSION); 8314@end example 8315 8316The @code{Type_Invariant} pragma is intended to be an exact 8317replacement for the language-defined @code{Type_Invariant} 8318aspect, and shares its restrictions and semantics. It differs 8319from the language defined @code{Invariant} pragma in that it 8320does not permit a string parameter, and it is 8321controlled by the assertion identifier @code{Type_Invariant} 8322rather than @code{Invariant}. 8323 8324@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 8325@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{103}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{104} 8326@section Pragma Type_Invariant_Class 8327 8328 8329Syntax: 8330 8331@example 8332pragma Type_Invariant_Class 8333 ([Entity =>] type_LOCAL_NAME, 8334 [Check =>] EXPRESSION); 8335@end example 8336 8337The @code{Type_Invariant_Class} pragma is intended to be an exact 8338replacement for the language-defined @code{Type_Invariant'Class} 8339aspect, and shares its restrictions and semantics. 8340 8341Note: This pragma is called @code{Type_Invariant_Class} rather than 8342@code{Type_Invariant'Class} because the latter would not be strictly 8343conforming to the allowed syntax for pragmas. The motivation 8344for providing pragmas equivalent to the aspects is to allow a program 8345to be written using the pragmas, and then compiled if necessary 8346using an Ada compiler that does not recognize the pragmas or 8347aspects, but is prepared to ignore the pragmas. The assertion 8348policy that controls this pragma is @code{Type_Invariant'Class}, 8349not @code{Type_Invariant_Class}. 8350 8351@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 8352@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{105} 8353@section Pragma Unchecked_Union 8354 8355 8356@geindex Unions in C 8357 8358Syntax: 8359 8360@example 8361pragma Unchecked_Union (first_subtype_LOCAL_NAME); 8362@end example 8363 8364This pragma is used to specify a representation of a record type that is 8365equivalent to a C union. It was introduced as a GNAT implementation defined 8366pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 8367pragma, making it language defined, and GNAT fully implements this extended 8368version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 8369details, consult the Ada 2012 Reference Manual, section B.3.3. 8370 8371@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 8372@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{106} 8373@section Pragma Unevaluated_Use_Of_Old 8374 8375 8376@geindex Attribute Old 8377 8378@geindex Attribute Loop_Entry 8379 8380@geindex Unevaluated_Use_Of_Old 8381 8382Syntax: 8383 8384@example 8385pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 8386@end example 8387 8388This pragma controls the processing of attributes Old and Loop_Entry. 8389If either of these attributes is used in a potentially unevaluated 8390expression (e.g. the then or else parts of an if expression), then 8391normally this usage is considered illegal if the prefix of the attribute 8392is other than an entity name. The language requires this 8393behavior for Old, and GNAT copies the same rule for Loop_Entry. 8394 8395The reason for this rule is that otherwise, we can have a situation 8396where we save the Old value, and this results in an exception, even 8397though we might not evaluate the attribute. Consider this example: 8398 8399@example 8400package UnevalOld is 8401 K : Character; 8402 procedure U (A : String; C : Boolean) -- ERROR 8403 with Post => (if C then A(1)'Old = K else True); 8404end; 8405@end example 8406 8407If procedure U is called with a string with a lower bound of 2, and 8408C false, then an exception would be raised trying to evaluate A(1) 8409on entry even though the value would not be actually used. 8410 8411Although the rule guarantees against this possibility, it is sometimes 8412too restrictive. For example if we know that the string has a lower 8413bound of 1, then we will never raise an exception. 8414The pragma @code{Unevaluated_Use_Of_Old} can be 8415used to modify this behavior. If the argument is @code{Error} then an 8416error is given (this is the default RM behavior). If the argument is 8417@code{Warn} then the usage is allowed as legal but with a warning 8418that an exception might be raised. If the argument is @code{Allow} 8419then the usage is allowed as legal without generating a warning. 8420 8421This pragma may appear as a configuration pragma, or in a declarative 8422part or package specification. In the latter case it applies to 8423uses up to the end of the corresponding statement sequence or 8424sequence of package declarations. 8425 8426@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 8427@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{107} 8428@section Pragma Unimplemented_Unit 8429 8430 8431Syntax: 8432 8433@example 8434pragma Unimplemented_Unit; 8435@end example 8436 8437If this pragma occurs in a unit that is processed by the compiler, GNAT 8438aborts with the message @code{xxx not implemented}, where 8439@code{xxx} is the name of the current compilation unit. This pragma is 8440intended to allow the compiler to handle unimplemented library units in 8441a clean manner. 8442 8443The abort only happens if code is being generated. Thus you can use 8444specs of unimplemented packages in syntax or semantic checking mode. 8445 8446@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas 8447@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{109} 8448@section Pragma Universal_Aliasing 8449 8450 8451Syntax: 8452 8453@example 8454pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 8455@end example 8456 8457@code{type_LOCAL_NAME} must refer to a type declaration in the current 8458declarative part. The effect is to inhibit strict type-based aliasing 8459optimization for the given type. In other words, the effect is as though 8460access types designating this type were subject to pragma No_Strict_Aliasing. 8461For a detailed description of the strict aliasing optimization, and the 8462situations in which it must be suppressed, see the section on 8463@code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}. 8464 8465@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas 8466@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{10b} 8467@section Pragma Universal_Data 8468 8469 8470Syntax: 8471 8472@example 8473pragma Universal_Data [(library_unit_Name)]; 8474@end example 8475 8476This pragma is supported only for the AAMP target and is ignored for 8477other targets. The pragma specifies that all library-level objects 8478(Counter 0 data) associated with the library unit are to be accessed 8479and updated using universal addressing (24-bit addresses for AAMP5) 8480rather than the default of 16-bit Data Environment (DENV) addressing. 8481Use of this pragma will generally result in less efficient code for 8482references to global data associated with the library unit, but 8483allows such data to be located anywhere in memory. This pragma is 8484a library unit pragma, but can also be used as a configuration pragma 8485(including use in the @code{gnat.adc} file). The functionality 8486of this pragma is also available by applying the -univ switch on the 8487compilations of units where universal addressing of the data is desired. 8488 8489@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas 8490@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{10d} 8491@section Pragma Unmodified 8492 8493 8494@geindex Warnings 8495@geindex unmodified 8496 8497Syntax: 8498 8499@example 8500pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8501@end example 8502 8503This pragma signals that the assignable entities (variables, 8504@code{out} parameters, @code{in out} parameters) whose names are listed are 8505deliberately not assigned in the current source unit. This 8506suppresses warnings about the 8507entities being referenced but not assigned, and in addition a warning will be 8508generated if one of these entities is in fact assigned in the 8509same unit as the pragma (or in the corresponding body, or one 8510of its subunits). 8511 8512This is particularly useful for clearly signaling that a particular 8513parameter is not modified, even though the spec suggests that it might 8514be. 8515 8516For the variable case, warnings are never given for unreferenced variables 8517whose name contains one of the substrings 8518@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8519are typically to be used in cases where such warnings are expected. 8520Thus it is never necessary to use @code{pragma Unmodified} for such 8521variables, though it is harmless to do so. 8522 8523@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8524@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10f} 8525@section Pragma Unreferenced 8526 8527 8528@geindex Warnings 8529@geindex unreferenced 8530 8531Syntax: 8532 8533@example 8534pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8535pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8536@end example 8537 8538This pragma signals that the entities whose names are listed are 8539deliberately not referenced in the current source unit after the 8540occurrence of the pragma. This 8541suppresses warnings about the 8542entities being unreferenced, and in addition a warning will be 8543generated if one of these entities is in fact subsequently referenced in the 8544same unit as the pragma (or in the corresponding body, or one 8545of its subunits). 8546 8547This is particularly useful for clearly signaling that a particular 8548parameter is not referenced in some particular subprogram implementation 8549and that this is deliberate. It can also be useful in the case of 8550objects declared only for their initialization or finalization side 8551effects. 8552 8553If @code{LOCAL_NAME} identifies more than one matching homonym in the 8554current scope, then the entity most recently declared is the one to which 8555the pragma applies. Note that in the case of accept formals, the pragma 8556Unreferenced may appear immediately after the keyword @code{do} which 8557allows the indication of whether or not accept formals are referenced 8558or not to be given individually for each accept statement. 8559 8560The left hand side of an assignment does not count as a reference for the 8561purpose of this pragma. Thus it is fine to assign to an entity for which 8562pragma Unreferenced is given. 8563 8564Note that if a warning is desired for all calls to a given subprogram, 8565regardless of whether they occur in the same unit as the subprogram 8566declaration, then this pragma should not be used (calls from another 8567unit would not be flagged); pragma Obsolescent can be used instead 8568for this purpose, see @ref{ad,,Pragma Obsolescent}. 8569 8570The second form of pragma @code{Unreferenced} is used within a context 8571clause. In this case the arguments must be unit names of units previously 8572mentioned in @code{with} clauses (similar to the usage of pragma 8573@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 8574units and unreferenced entities within these units. 8575 8576For the variable case, warnings are never given for unreferenced variables 8577whose name contains one of the substrings 8578@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8579are typically to be used in cases where such warnings are expected. 8580Thus it is never necessary to use @code{pragma Unreferenced} for such 8581variables, though it is harmless to do so. 8582 8583@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8584@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{111} 8585@section Pragma Unreferenced_Objects 8586 8587 8588@geindex Warnings 8589@geindex unreferenced 8590 8591Syntax: 8592 8593@example 8594pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8595@end example 8596 8597This pragma signals that for the types or subtypes whose names are 8598listed, objects which are declared with one of these types or subtypes may 8599not be referenced, and if no references appear, no warnings are given. 8600 8601This is particularly useful for objects which are declared solely for their 8602initialization and finalization effect. Such variables are sometimes referred 8603to as RAII variables (Resource Acquisition Is Initialization). Using this 8604pragma on the relevant type (most typically a limited controlled type), the 8605compiler will automatically suppress unwanted warnings about these variables 8606not being referenced. 8607 8608@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8609@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{112} 8610@section Pragma Unreserve_All_Interrupts 8611 8612 8613Syntax: 8614 8615@example 8616pragma Unreserve_All_Interrupts; 8617@end example 8618 8619Normally certain interrupts are reserved to the implementation. Any attempt 8620to attach an interrupt causes Program_Error to be raised, as described in 8621RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 8622many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8623reserved to the implementation, so that @code{Ctrl-C} can be used to 8624interrupt execution. 8625 8626If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 8627a program, then all such interrupts are unreserved. This allows the 8628program to handle these interrupts, but disables their standard 8629functions. For example, if this pragma is used, then pressing 8630@code{Ctrl-C} will not automatically interrupt execution. However, 8631a program can then handle the @code{SIGINT} interrupt as it chooses. 8632 8633For a full list of the interrupts handled in a specific implementation, 8634see the source code for the spec of @code{Ada.Interrupts.Names} in 8635file @code{a-intnam.ads}. This is a target dependent file that contains the 8636list of interrupts recognized for a given target. The documentation in 8637this file also specifies what interrupts are affected by the use of 8638the @code{Unreserve_All_Interrupts} pragma. 8639 8640For a more general facility for controlling what interrupts can be 8641handled, see pragma @code{Interrupt_State}, which subsumes the functionality 8642of the @code{Unreserve_All_Interrupts} pragma. 8643 8644@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8645@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{113} 8646@section Pragma Unsuppress 8647 8648 8649Syntax: 8650 8651@example 8652pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8653@end example 8654 8655This pragma undoes the effect of a previous pragma @code{Suppress}. If 8656there is no corresponding pragma @code{Suppress} in effect, it has no 8657effect. The range of the effect is the same as for pragma 8658@code{Suppress}. The meaning of the arguments is identical to that used 8659in pragma @code{Suppress}. 8660 8661One important application is to ensure that checks are on in cases where 8662code depends on the checks for its correct functioning, so that the code 8663will compile correctly even if the compiler switches are set to suppress 8664checks. For example, in a program that depends on external names of tagged 8665types and wants to ensure that the duplicated tag check occurs even if all 8666run-time checks are suppressed by a compiler switch, the following 8667configuration pragma will ensure this test is not suppressed: 8668 8669@example 8670pragma Unsuppress (Duplicated_Tag_Check); 8671@end example 8672 8673This pragma is standard in Ada 2005. It is available in all earlier versions 8674of Ada as an implementation-defined pragma. 8675 8676Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8677number of implementation-defined check names. See the description of pragma 8678@code{Suppress} for full details. 8679 8680@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas 8681@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{114} 8682@section Pragma Use_VADS_Size 8683 8684 8685@geindex Size 8686@geindex VADS compatibility 8687 8688@geindex Rational profile 8689 8690Syntax: 8691 8692@example 8693pragma Use_VADS_Size; 8694@end example 8695 8696This is a configuration pragma. In a unit to which it applies, any use 8697of the 'Size attribute is automatically interpreted as a use of the 8698'VADS_Size attribute. Note that this may result in incorrect semantic 8699processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8700the handling of existing code which depends on the interpretation of Size 8701as implemented in the VADS compiler. See description of the VADS_Size 8702attribute for further details. 8703 8704@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas 8705@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{116} 8706@section Pragma Unused 8707 8708 8709@geindex Warnings 8710@geindex unused 8711 8712Syntax: 8713 8714@example 8715pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); 8716@end example 8717 8718This pragma signals that the assignable entities (variables, 8719@code{out} parameters, and @code{in out} parameters) whose names are listed 8720deliberately do not get assigned or referenced in the current source unit 8721after the occurrence of the pragma in the current source unit. This 8722suppresses warnings about the entities that are unreferenced and/or not 8723assigned, and, in addition, a warning will be generated if one of these 8724entities gets assigned or subsequently referenced in the same unit as the 8725pragma (in the corresponding body or one of its subunits). 8726 8727This is particularly useful for clearly signaling that a particular 8728parameter is not modified or referenced, even though the spec suggests 8729that it might be. 8730 8731For the variable case, warnings are never given for unreferenced 8732variables whose name contains one of the substrings 8733@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8734are typically to be used in cases where such warnings are expected. 8735Thus it is never necessary to use @code{pragma Unmodified} for such 8736variables, though it is harmless to do so. 8737 8738@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas 8739@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{117} 8740@section Pragma Validity_Checks 8741 8742 8743Syntax: 8744 8745@example 8746pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8747@end example 8748 8749This pragma is used in conjunction with compiler switches to control the 8750built-in validity checking provided by GNAT. The compiler switches, if set 8751provide an initial setting for the switches, and this pragma may be used 8752to modify these settings, or the settings may be provided entirely by 8753the use of the pragma. This pragma can be used anywhere that a pragma 8754is legal, including use as a configuration pragma (including use in 8755the @code{gnat.adc} file). 8756 8757The form with a string literal specifies which validity options are to be 8758activated. The validity checks are first set to include only the default 8759reference manual settings, and then a string of letters in the string 8760specifies the exact set of options required. The form of this string 8761is exactly as described for the @emph{-gnatVx} compiler switch (see the 8762GNAT User's Guide for details). For example the following two 8763methods can be used to enable validity checking for mode @code{in} and 8764@code{in out} subprogram parameters: 8765 8766 8767@itemize * 8768 8769@item 8770@example 8771pragma Validity_Checks ("im"); 8772@end example 8773 8774@item 8775@example 8776$ gcc -c -gnatVim ... 8777@end example 8778@end itemize 8779 8780The form ALL_CHECKS activates all standard checks (its use is equivalent 8781to the use of the @code{gnatva} switch. 8782 8783The forms with @code{Off} and @code{On} 8784can be used to temporarily disable validity checks 8785as shown in the following example: 8786 8787@example 8788pragma Validity_Checks ("c"); -- validity checks for copies 8789pragma Validity_Checks (Off); -- turn off validity checks 8790A := B; -- B will not be validity checked 8791pragma Validity_Checks (On); -- turn validity checks back on 8792A := C; -- C will be validity checked 8793@end example 8794 8795@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8796@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{118} 8797@section Pragma Volatile 8798 8799 8800Syntax: 8801 8802@example 8803pragma Volatile (LOCAL_NAME); 8804@end example 8805 8806This pragma is defined by the Ada Reference Manual, and the GNAT 8807implementation is fully conformant with this definition. The reason it 8808is mentioned in this section is that a pragma of the same name was supplied 8809in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8810implementation of pragma Volatile is upwards compatible with the 8811implementation in DEC Ada 83. 8812 8813@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8814@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{119}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{11a} 8815@section Pragma Volatile_Full_Access 8816 8817 8818Syntax: 8819 8820@example 8821pragma Volatile_Full_Access (LOCAL_NAME); 8822@end example 8823 8824This is similar in effect to pragma Volatile, except that any reference to the 8825object is guaranteed to be done only with instructions that read or write all 8826the bits of the object. Furthermore, if the object is of a composite type, 8827then any reference to a component of the object is guaranteed to read and/or 8828write all the bits of the object. 8829 8830The intention is that this be suitable for use with memory-mapped I/O devices 8831on some machines. Note that there are two important respects in which this is 8832different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} 8833object is not a sequential action in the RM 9.10 sense and, therefore, does 8834not create a synchronization point. Second, in the case of @code{pragma Atomic}, 8835there is no guarantee that all the bits will be accessed if the reference 8836is not to the whole object; the compiler is allowed (and generally will) 8837access only part of the object in this case. 8838 8839It is not permissible to specify @code{Atomic} and @code{Volatile_Full_Access} for 8840the same object. 8841 8842It is not permissible to specify @code{Volatile_Full_Access} for a composite 8843(record or array) type or object that has at least one @code{Aliased} component. 8844 8845@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8846@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11c} 8847@section Pragma Volatile_Function 8848 8849 8850Syntax: 8851 8852@example 8853pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8854@end example 8855 8856For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} 8857in the SPARK 2014 Reference Manual, section 7.1.2. 8858 8859@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8860@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11d} 8861@section Pragma Warning_As_Error 8862 8863 8864Syntax: 8865 8866@example 8867pragma Warning_As_Error (static_string_EXPRESSION); 8868@end example 8869 8870This configuration pragma allows the programmer to specify a set 8871of warnings that will be treated as errors. Any warning which 8872matches the pattern given by the pragma argument will be treated 8873as an error. This gives much more precise control that -gnatwe 8874which treats all warnings as errors. 8875 8876The pattern may contain asterisks, which match zero or more characters in 8877the message. For example, you can use 8878@code{pragma Warning_As_Error ("bits of*unused")} to treat the warning 8879message @code{warning: 960 bits of "a" unused} as an error. No other regular 8880expression notations are permitted. All characters other than asterisk in 8881these three specific cases are treated as literal characters in the match. 8882The match is case insensitive, for example XYZ matches xyz. 8883 8884Note that the pattern matches if it occurs anywhere within the warning 8885message string (it is not necessary to put an asterisk at the start and 8886the end of the message, since this is implied). 8887 8888Another possibility for the static_string_EXPRESSION which works whether 8889or not error tags are enabled (@emph{-gnatw.d}) is to use the 8890@emph{-gnatw} tag string, enclosed in brackets, 8891as shown in the example below, to treat a class of warnings as errors. 8892 8893The above use of patterns to match the message applies only to warning 8894messages generated by the front end. This pragma can also be applied to 8895warnings provided by the back end and mentioned in @ref{11e,,Pragma Warnings}. 8896By using a single full @emph{-Wxxx} switch in the pragma, such warnings 8897can also be treated as errors. 8898 8899The pragma can appear either in a global configuration pragma file 8900(e.g. @code{gnat.adc}), or at the start of a file. Given a global 8901configuration pragma file containing: 8902 8903@example 8904pragma Warning_As_Error ("[-gnatwj]"); 8905@end example 8906 8907which will treat all obsolescent feature warnings as errors, the 8908following program compiles as shown (compile options here are 8909@emph{-gnatwa.d -gnatl -gnatj55}). 8910 8911@example 8912 1. pragma Warning_As_Error ("*never assigned*"); 8913 2. function Warnerr return String is 8914 3. X : Integer; 8915 | 8916 >>> error: variable "X" is never read and 8917 never assigned [-gnatwv] [warning-as-error] 8918 8919 4. Y : Integer; 8920 | 8921 >>> warning: variable "Y" is assigned but 8922 never read [-gnatwu] 8923 8924 5. begin 8925 6. Y := 0; 8926 7. return %ABC%; 8927 | 8928 >>> error: use of "%" is an obsolescent 8929 feature (RM J.2(4)), use """ instead 8930 [-gnatwj] [warning-as-error] 8931 8932 8. end; 8933 89348 lines: No errors, 3 warnings (2 treated as errors) 8935@end example 8936 8937Note that this pragma does not affect the set of warnings issued in 8938any way, it merely changes the effect of a matching warning if one 8939is produced as a result of other warnings options. As shown in this 8940example, if the pragma results in a warning being treated as an error, 8941the tag is changed from "warning:" to "error:" and the string 8942"[warning-as-error]" is appended to the end of the message. 8943 8944@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 8945@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{11f}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11e} 8946@section Pragma Warnings 8947 8948 8949Syntax: 8950 8951@example 8952pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 8953 8954DETAILS ::= On | Off 8955DETAILS ::= On | Off, local_NAME 8956DETAILS ::= static_string_EXPRESSION 8957DETAILS ::= On | Off, static_string_EXPRESSION 8958 8959TOOL_NAME ::= GNAT | GNATProve 8960 8961REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 8962@end example 8963 8964Note: in Ada 83 mode, a string literal may be used in place of a static string 8965expression (which does not exist in Ada 83). 8966 8967Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the 8968second form is always understood. If the intention is to use 8969the fourth form, then you can write @code{NAME & ""} to force the 8970intepretation as a @emph{static_string_EXPRESSION}. 8971 8972Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted 8973that way. The use of the @code{TOOL_NAME} argument is relevant only to users 8974of SPARK and GNATprove, see last part of this section for details. 8975 8976Normally warnings are enabled, with the output being controlled by 8977the command line switch. Warnings (@code{Off}) turns off generation of 8978warnings until a Warnings (@code{On}) is encountered or the end of the 8979current unit. If generation of warnings is turned off using this 8980pragma, then some or all of the warning messages are suppressed, 8981regardless of the setting of the command line switches. 8982 8983The @code{Reason} parameter may optionally appear as the last argument 8984in any of the forms of this pragma. It is intended purely for the 8985purposes of documenting the reason for the @code{Warnings} pragma. 8986The compiler will check that the argument is a static string but 8987otherwise ignore this argument. Other tools may provide specialized 8988processing for this string. 8989 8990The form with a single argument (or two arguments if Reason present), 8991where the first argument is @code{ON} or @code{OFF} 8992may be used as a configuration pragma. 8993 8994If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for 8995the specified entity. This suppression is effective from the point where 8996it occurs till the end of the extended scope of the variable (similar to 8997the scope of @code{Suppress}). This form cannot be used as a configuration 8998pragma. 8999 9000In the case where the first argument is other than @code{ON} or 9001@code{OFF}, 9002the third form with a single static_string_EXPRESSION argument (and possible 9003reason) provides more precise 9004control over which warnings are active. The string is a list of letters 9005specifying which warnings are to be activated and which deactivated. The 9006code for these letters is the same as the string used in the command 9007line switch controlling warnings. For a brief summary, use the gnatmake 9008command with no arguments, which will generate usage information containing 9009the list of warnings switches supported. For 9010full details see the section on @code{Warning Message Control} in the 9011@cite{GNAT User's Guide}. 9012This form can also be used as a configuration pragma. 9013 9014The warnings controlled by the @code{-gnatw} switch are generated by the 9015front end of the compiler. The GCC back end can provide additional warnings 9016and they are controlled by the @code{-W} switch. Such warnings can be 9017identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the 9018message which designates the @code{-W@emph{xxx}} switch that controls the message. 9019The form with a single @emph{static_string_EXPRESSION} argument also works for these 9020warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this 9021case. The above reference lists a few examples of these additional warnings. 9022 9023The specified warnings will be in effect until the end of the program 9024or another pragma @code{Warnings} is encountered. The effect of the pragma is 9025cumulative. Initially the set of warnings is the standard default set 9026as possibly modified by compiler switches. Then each pragma Warning 9027modifies this set of warnings as specified. This form of the pragma may 9028also be used as a configuration pragma. 9029 9030The fourth form, with an @code{On|Off} parameter and a string, is used to 9031control individual messages, based on their text. The string argument 9032is a pattern that is used to match against the text of individual 9033warning messages (not including the initial "warning: " tag). 9034 9035The pattern may contain asterisks, which match zero or more characters in 9036the message. For example, you can use 9037@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning 9038message @code{warning: 960 bits of "a" unused}. No other regular 9039expression notations are permitted. All characters other than asterisk in 9040these three specific cases are treated as literal characters in the match. 9041The match is case insensitive, for example XYZ matches xyz. 9042 9043Note that the pattern matches if it occurs anywhere within the warning 9044message string (it is not necessary to put an asterisk at the start and 9045the end of the message, since this is implied). 9046 9047The above use of patterns to match the message applies only to warning 9048messages generated by the front end. This form of the pragma with a string 9049argument can also be used to control warnings provided by the back end and 9050mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, 9051such warnings can be turned on and off. 9052 9053There are two ways to use the pragma in this form. The OFF form can be used 9054as a configuration pragma. The effect is to suppress all warnings (if any) 9055that match the pattern string throughout the compilation (or match the 9056-W switch in the back end case). 9057 9058The second usage is to suppress a warning locally, and in this case, two 9059pragmas must appear in sequence: 9060 9061@example 9062pragma Warnings (Off, Pattern); 9063... code where given warning is to be suppressed 9064pragma Warnings (On, Pattern); 9065@end example 9066 9067In this usage, the pattern string must match in the Off and On 9068pragmas, and (if @emph{-gnatw.w} is given) at least one matching 9069warning must be suppressed. 9070 9071Note: if the ON form is not found, then the effect of the OFF form extends 9072until the end of the file (pragma Warnings is purely textual, so its effect 9073does not stop at the end of the enclosing scope). 9074 9075Note: to write a string that will match any warning, use the string 9076@code{"***"}. It will not work to use a single asterisk or two 9077asterisks since this looks like an operator name. This form with three 9078asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching 9079@code{pragma Warnings (On, "***")} will be required. This can be 9080helpful in avoiding forgetting to turn warnings back on. 9081 9082Note: the debug flag @code{-gnatd.i} (@code{/NOWARNINGS_PRAGMAS} in VMS) can be 9083used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 9084be useful in checking whether obsolete pragmas in existing programs are hiding 9085real problems. 9086 9087Note: pragma Warnings does not affect the processing of style messages. See 9088separate entry for pragma Style_Checks for control of style messages. 9089 9090Users of the formal verification tool GNATprove for the SPARK subset of Ada may 9091use the version of the pragma with a @code{TOOL_NAME} parameter. 9092 9093If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the 9094compiler or @code{GNATprove} for the formal verification tool. A given tool only 9095takes into account pragma Warnings that do not specify a tool name, or that 9096specify the matching tool name. This makes it possible to disable warnings 9097selectively for each tool, and as a consequence to detect useless pragma 9098Warnings with switch @code{-gnatw.w}. 9099 9100@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 9101@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{120} 9102@section Pragma Weak_External 9103 9104 9105Syntax: 9106 9107@example 9108pragma Weak_External ([Entity =>] LOCAL_NAME); 9109@end example 9110 9111@code{LOCAL_NAME} must refer to an object that is declared at the library 9112level. This pragma specifies that the given entity should be marked as a 9113weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 9114in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead 9115of a regular symbol, that is to say a symbol that does not have to be 9116resolved by the linker if used in conjunction with a pragma Import. 9117 9118When a weak symbol is not resolved by the linker, its address is set to 9119zero. This is useful in writing interfaces to external modules that may 9120or may not be linked in the final executable, for example depending on 9121configuration settings. 9122 9123If a program references at run time an entity to which this pragma has been 9124applied, and the corresponding symbol was not resolved at link time, then 9125the execution of the program is erroneous. It is not erroneous to take the 9126Address of such an entity, for example to guard potential references, 9127as shown in the example below. 9128 9129Some file formats do not support weak symbols so not all target machines 9130support this pragma. 9131 9132@example 9133-- Example of the use of pragma Weak_External 9134 9135package External_Module is 9136 key : Integer; 9137 pragma Import (C, key); 9138 pragma Weak_External (key); 9139 function Present return boolean; 9140end External_Module; 9141 9142with System; use System; 9143package body External_Module is 9144 function Present return boolean is 9145 begin 9146 return key'Address /= System.Null_Address; 9147 end Present; 9148end External_Module; 9149@end example 9150 9151@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 9152@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{121} 9153@section Pragma Wide_Character_Encoding 9154 9155 9156Syntax: 9157 9158@example 9159pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 9160@end example 9161 9162This pragma specifies the wide character encoding to be used in program 9163source text appearing subsequently. It is a configuration pragma, but may 9164also be used at any point that a pragma is allowed, and it is permissible 9165to have more than one such pragma in a file, allowing multiple encodings 9166to appear within the same file. 9167 9168However, note that the pragma cannot immediately precede the relevant 9169wide character, because then the previous encoding will still be in 9170effect, causing "illegal character" errors. 9171 9172The argument can be an identifier or a character literal. In the identifier 9173case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 9174@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 9175case it is correspondingly one of the characters @code{h}, @code{u}, 9176@code{s}, @code{e}, @code{8}, or @code{b}. 9177 9178Note that when the pragma is used within a file, it affects only the 9179encoding within that file, and does not affect withed units, specs, 9180or subunits. 9181 9182@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 9183@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{122}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{123}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{124} 9184@chapter Implementation Defined Aspects 9185 9186 9187Ada defines (throughout the Ada 2012 reference manual, summarized 9188in Annex K) a set of aspects that can be specified for certain entities. 9189These language defined aspects are implemented in GNAT in Ada 2012 mode 9190and work as described in the Ada 2012 Reference Manual. 9191 9192In addition, Ada 2012 allows implementations to define additional aspects 9193whose meaning is defined by the implementation. GNAT provides 9194a number of these implementation-defined aspects which can be used 9195to extend and enhance the functionality of the compiler. This section of 9196the GNAT reference manual describes these additional aspects. 9197 9198Note that any program using these aspects may not be portable to 9199other compilers (although GNAT implements this set of aspects on all 9200platforms). Therefore if portability to other compilers is an important 9201consideration, you should minimize the use of these aspects. 9202 9203Note that for many of these aspects, the effect is essentially similar 9204to the use of a pragma or attribute specification with the same name 9205applied to the entity. For example, if we write: 9206 9207@example 9208type R is range 1 .. 100 9209 with Value_Size => 10; 9210@end example 9211 9212then the effect is the same as: 9213 9214@example 9215type R is range 1 .. 100; 9216for R'Value_Size use 10; 9217@end example 9218 9219and if we write: 9220 9221@example 9222type R is new Integer 9223 with Shared => True; 9224@end example 9225 9226then the effect is the same as: 9227 9228@example 9229type R is new Integer; 9230pragma Shared (R); 9231@end example 9232 9233In the documentation below, such cases are simply marked 9234as being boolean aspects equivalent to the corresponding pragma 9235or attribute definition clause. 9236 9237@menu 9238* Aspect Abstract_State:: 9239* Aspect Annotate:: 9240* Aspect Async_Readers:: 9241* Aspect Async_Writers:: 9242* Aspect Constant_After_Elaboration:: 9243* Aspect Contract_Cases:: 9244* Aspect Depends:: 9245* Aspect Default_Initial_Condition:: 9246* Aspect Dimension:: 9247* Aspect Dimension_System:: 9248* Aspect Disable_Controlled:: 9249* Aspect Effective_Reads:: 9250* Aspect Effective_Writes:: 9251* Aspect Extensions_Visible:: 9252* Aspect Favor_Top_Level:: 9253* Aspect Ghost:: 9254* Aspect Global:: 9255* Aspect Initial_Condition:: 9256* Aspect Initializes:: 9257* Aspect Inline_Always:: 9258* Aspect Invariant:: 9259* Aspect Invariant'Class:: 9260* Aspect Iterable:: 9261* Aspect Linker_Section:: 9262* Aspect Lock_Free:: 9263* Aspect Max_Queue_Length:: 9264* Aspect No_Elaboration_Code_All:: 9265* Aspect No_Inline:: 9266* Aspect No_Tagged_Streams:: 9267* Aspect Object_Size:: 9268* Aspect Obsolescent:: 9269* Aspect Part_Of:: 9270* Aspect Persistent_BSS:: 9271* Aspect Predicate:: 9272* Aspect Pure_Function:: 9273* Aspect Refined_Depends:: 9274* Aspect Refined_Global:: 9275* Aspect Refined_Post:: 9276* Aspect Refined_State:: 9277* Aspect Remote_Access_Type:: 9278* Aspect Secondary_Stack_Size:: 9279* Aspect Scalar_Storage_Order:: 9280* Aspect Shared:: 9281* Aspect Simple_Storage_Pool:: 9282* Aspect Simple_Storage_Pool_Type:: 9283* Aspect SPARK_Mode:: 9284* Aspect Suppress_Debug_Info:: 9285* Aspect Suppress_Initialization:: 9286* Aspect Test_Case:: 9287* Aspect Thread_Local_Storage:: 9288* Aspect Universal_Aliasing:: 9289* Aspect Universal_Data:: 9290* Aspect Unmodified:: 9291* Aspect Unreferenced:: 9292* Aspect Unreferenced_Objects:: 9293* Aspect Value_Size:: 9294* Aspect Volatile_Full_Access:: 9295* Aspect Volatile_Function:: 9296* Aspect Warnings:: 9297 9298@end menu 9299 9300@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects 9301@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{125} 9302@section Aspect Abstract_State 9303 9304 9305@geindex Abstract_State 9306 9307This aspect is equivalent to @ref{1c,,pragma Abstract_State}. 9308 9309@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 9310@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{126} 9311@section Aspect Annotate 9312 9313 9314@geindex Annotate 9315 9316There are three forms of this aspect (where ID is an identifier, 9317and ARG is a general expression), 9318corresponding to @ref{29,,pragma Annotate}. 9319 9320 9321@table @asis 9322 9323@item @emph{Annotate => ID} 9324 9325Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9326 9327@item @emph{Annotate => (ID)} 9328 9329Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9330 9331@item @emph{Annotate => (ID ,ID @{, ARG@})} 9332 9333Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} 9334@end table 9335 9336@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects 9337@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{127} 9338@section Aspect Async_Readers 9339 9340 9341@geindex Async_Readers 9342 9343This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. 9344 9345@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 9346@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{128} 9347@section Aspect Async_Writers 9348 9349 9350@geindex Async_Writers 9351 9352This boolean aspect is equivalent to @ref{33,,pragma Async_Writers}. 9353 9354@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 9355@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{129} 9356@section Aspect Constant_After_Elaboration 9357 9358 9359@geindex Constant_After_Elaboration 9360 9361This aspect is equivalent to @ref{44,,pragma Constant_After_Elaboration}. 9362 9363@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 9364@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{12a} 9365@section Aspect Contract_Cases 9366 9367 9368@geindex Contract_Cases 9369 9370This aspect is equivalent to @ref{46,,pragma Contract_Cases}, the sequence 9371of clauses being enclosed in parentheses so that syntactically it is an 9372aggregate. 9373 9374@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 9375@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12b} 9376@section Aspect Depends 9377 9378 9379@geindex Depends 9380 9381This aspect is equivalent to @ref{55,,pragma Depends}. 9382 9383@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 9384@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12c} 9385@section Aspect Default_Initial_Condition 9386 9387 9388@geindex Default_Initial_Condition 9389 9390This aspect is equivalent to @ref{50,,pragma Default_Initial_Condition}. 9391 9392@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 9393@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12d} 9394@section Aspect Dimension 9395 9396 9397@geindex Dimension 9398 9399The @code{Dimension} aspect is used to specify the dimensions of a given 9400subtype of a dimensioned numeric type. The aspect also specifies a symbol 9401used when doing formatted output of dimensioned quantities. The syntax is: 9402 9403@example 9404with Dimension => 9405 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 9406 9407SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 9408 9409DIMENSION_VALUE ::= 9410 RATIONAL 9411| others => RATIONAL 9412| DISCRETE_CHOICE_LIST => RATIONAL 9413 9414RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 9415@end example 9416 9417This aspect can only be applied to a subtype whose parent type has 9418a @code{Dimension_System} aspect. The aspect must specify values for 9419all dimensions of the system. The rational values are the powers of the 9420corresponding dimensions that are used by the compiler to verify that 9421physical (numeric) computations are dimensionally consistent. For example, 9422the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 9423For further examples of the usage 9424of this aspect, see package @code{System.Dim.Mks}. 9425Note that when the dimensioned type is an integer type, then any 9426dimension value must be an integer literal. 9427 9428@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 9429@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12e} 9430@section Aspect Dimension_System 9431 9432 9433@geindex Dimension_System 9434 9435The @code{Dimension_System} aspect is used to define a system of 9436dimensions that will be used in subsequent subtype declarations with 9437@code{Dimension} aspects that reference this system. The syntax is: 9438 9439@example 9440with Dimension_System => (DIMENSION @{, DIMENSION@}); 9441 9442DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 9443 [Unit_Symbol =>] SYMBOL, 9444 [Dim_Symbol =>] SYMBOL) 9445 9446SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 9447@end example 9448 9449This aspect is applied to a type, which must be a numeric derived type 9450(typically a floating-point type), that 9451will represent values within the dimension system. Each @code{DIMENSION} 9452corresponds to one particular dimension. A maximum of 7 dimensions may 9453be specified. @code{Unit_Name} is the name of the dimension (for example 9454@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 9455of this dimension (for example @code{m} for @code{Meter}). 9456@code{Dim_Symbol} gives 9457the identification within the dimension system (typically this is a 9458single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 9459The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 9460The @code{Dim_Symbol} is used in error messages when numeric operations have 9461inconsistent dimensions. 9462 9463GNAT provides the standard definition of the International MKS system in 9464the run-time package @code{System.Dim.Mks}. You can easily define 9465similar packages for cgs units or British units, and define conversion factors 9466between values in different systems. The MKS system is characterized by the 9467following aspect: 9468 9469@example 9470type Mks_Type is new Long_Long_Float with 9471 Dimension_System => ( 9472 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 9473 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 9474 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 9475 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 9476 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 9477 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 9478 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 9479@end example 9480 9481Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to 9482represent a theta character (avoiding the use of extended Latin-1 9483characters in this context). 9484 9485See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users 9486Guide for detailed examples of use of the dimension system. 9487 9488@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 9489@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12f} 9490@section Aspect Disable_Controlled 9491 9492 9493@geindex Disable_Controlled 9494 9495The aspect @code{Disable_Controlled} is defined for controlled record types. If 9496active, this aspect causes suppression of all related calls to @code{Initialize}, 9497@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, 9498where for example you might want a record to be controlled or not depending on 9499whether some run-time check is enabled or suppressed. 9500 9501@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 9502@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{130} 9503@section Aspect Effective_Reads 9504 9505 9506@geindex Effective_Reads 9507 9508This aspect is equivalent to @ref{5b,,pragma Effective_Reads}. 9509 9510@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 9511@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{131} 9512@section Aspect Effective_Writes 9513 9514 9515@geindex Effective_Writes 9516 9517This aspect is equivalent to @ref{5d,,pragma Effective_Writes}. 9518 9519@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 9520@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{132} 9521@section Aspect Extensions_Visible 9522 9523 9524@geindex Extensions_Visible 9525 9526This aspect is equivalent to @ref{69,,pragma Extensions_Visible}. 9527 9528@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 9529@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{133} 9530@section Aspect Favor_Top_Level 9531 9532 9533@geindex Favor_Top_Level 9534 9535This boolean aspect is equivalent to @ref{6e,,pragma Favor_Top_Level}. 9536 9537@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9538@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{134} 9539@section Aspect Ghost 9540 9541 9542@geindex Ghost 9543 9544This aspect is equivalent to @ref{71,,pragma Ghost}. 9545 9546@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9547@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{135} 9548@section Aspect Global 9549 9550 9551@geindex Global 9552 9553This aspect is equivalent to @ref{73,,pragma Global}. 9554 9555@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9556@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{136} 9557@section Aspect Initial_Condition 9558 9559 9560@geindex Initial_Condition 9561 9562This aspect is equivalent to @ref{81,,pragma Initial_Condition}. 9563 9564@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9565@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{137} 9566@section Aspect Initializes 9567 9568 9569@geindex Initializes 9570 9571This aspect is equivalent to @ref{83,,pragma Initializes}. 9572 9573@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9574@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{138} 9575@section Aspect Inline_Always 9576 9577 9578@geindex Inline_Always 9579 9580This boolean aspect is equivalent to @ref{86,,pragma Inline_Always}. 9581 9582@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects 9583@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{139} 9584@section Aspect Invariant 9585 9586 9587@geindex Invariant 9588 9589This aspect is equivalent to @ref{8d,,pragma Invariant}. It is a 9590synonym for the language defined aspect @code{Type_Invariant} except 9591that it is separately controllable using pragma @code{Assertion_Policy}. 9592 9593@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9594@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13a} 9595@section Aspect Invariant'Class 9596 9597 9598@geindex Invariant'Class 9599 9600This aspect is equivalent to @ref{104,,pragma Type_Invariant_Class}. It is a 9601synonym for the language defined aspect @code{Type_Invariant'Class} except 9602that it is separately controllable using pragma @code{Assertion_Policy}. 9603 9604@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects 9605@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13b} 9606@section Aspect Iterable 9607 9608 9609@geindex Iterable 9610 9611This aspect provides a light-weight mechanism for loops and quantified 9612expressions over container types, without the overhead imposed by the tampering 9613checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9614with six named components, of which the last three are optional: @code{First}, 9615@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. 9616When only the first three components are specified, only the 9617@code{for .. in} form of iteration over cursors is available. When @code{Element} 9618is specified, both this form and the @code{for .. of} form of iteration over 9619elements are available. If the last two components are specified, reverse 9620iterations over the container can be specified (analogous to what can be done 9621over predefined containers that support the @code{Reverse_Iterator} interface). 9622The following is a typical example of use: 9623 9624@example 9625type List is private with 9626 Iterable => (First => First_Cursor, 9627 Next => Advance, 9628 Has_Element => Cursor_Has_Element, 9629 [Element => Get_Element]); 9630@end example 9631 9632 9633@itemize * 9634 9635@item 9636The value denoted by @code{First} must denote a primitive operation of the 9637container type that returns a @code{Cursor}, which must a be a type declared in 9638the container package or visible from it. For example: 9639@end itemize 9640 9641@example 9642function First_Cursor (Cont : Container) return Cursor; 9643@end example 9644 9645 9646@itemize * 9647 9648@item 9649The value of @code{Next} is a primitive operation of the container type that takes 9650both a container and a cursor and yields a cursor. For example: 9651@end itemize 9652 9653@example 9654function Advance (Cont : Container; Position : Cursor) return Cursor; 9655@end example 9656 9657 9658@itemize * 9659 9660@item 9661The value of @code{Has_Element} is a primitive operation of the container type 9662that takes both a container and a cursor and yields a boolean. For example: 9663@end itemize 9664 9665@example 9666function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9667@end example 9668 9669 9670@itemize * 9671 9672@item 9673The value of @code{Element} is a primitive operation of the container type that 9674takes both a container and a cursor and yields an @code{Element_Type}, which must 9675be a type declared in the container package or visible from it. For example: 9676@end itemize 9677 9678@example 9679function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9680@end example 9681 9682This aspect is used in the GNAT-defined formal container packages. 9683 9684@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9685@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13c} 9686@section Aspect Linker_Section 9687 9688 9689@geindex Linker_Section 9690 9691This aspect is equivalent to @ref{95,,pragma Linker_Section}. 9692 9693@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects 9694@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13d} 9695@section Aspect Lock_Free 9696 9697 9698@geindex Lock_Free 9699 9700This boolean aspect is equivalent to @ref{97,,pragma Lock_Free}. 9701 9702@node Aspect Max_Queue_Length,Aspect No_Elaboration_Code_All,Aspect Lock_Free,Implementation Defined Aspects 9703@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13e} 9704@section Aspect Max_Queue_Length 9705 9706 9707@geindex Max_Queue_Length 9708 9709This aspect is equivalent to @ref{9f,,pragma Max_Queue_Length}. 9710 9711@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect Max_Queue_Length,Implementation Defined Aspects 9712@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13f} 9713@section Aspect No_Elaboration_Code_All 9714 9715 9716@geindex No_Elaboration_Code_All 9717 9718This aspect is equivalent to @ref{a3,,pragma No_Elaboration_Code_All} 9719for a program unit. 9720 9721@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9722@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{140} 9723@section Aspect No_Inline 9724 9725 9726@geindex No_Inline 9727 9728This boolean aspect is equivalent to @ref{a6,,pragma No_Inline}. 9729 9730@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects 9731@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{141} 9732@section Aspect No_Tagged_Streams 9733 9734 9735@geindex No_Tagged_Streams 9736 9737This aspect is equivalent to @ref{aa,,pragma No_Tagged_Streams} with an 9738argument specifying a root tagged type (thus this aspect can only be 9739applied to such a type). 9740 9741@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects 9742@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{142} 9743@section Aspect Object_Size 9744 9745 9746@geindex Object_Size 9747 9748This aspect is equivalent to @ref{143,,attribute Object_Size}. 9749 9750@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9751@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{144} 9752@section Aspect Obsolescent 9753 9754 9755@geindex Obsolsecent 9756 9757This aspect is equivalent to @ref{ad,,pragma Obsolescent}. Note that the 9758evaluation of this aspect happens at the point of occurrence, it is not 9759delayed until the freeze point. 9760 9761@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9762@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{145} 9763@section Aspect Part_Of 9764 9765 9766@geindex Part_Of 9767 9768This aspect is equivalent to @ref{b5,,pragma Part_Of}. 9769 9770@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9771@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{146} 9772@section Aspect Persistent_BSS 9773 9774 9775@geindex Persistent_BSS 9776 9777This boolean aspect is equivalent to @ref{b8,,pragma Persistent_BSS}. 9778 9779@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9780@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{147} 9781@section Aspect Predicate 9782 9783 9784@geindex Predicate 9785 9786This aspect is equivalent to @ref{c1,,pragma Predicate}. It is thus 9787similar to the language defined aspects @code{Dynamic_Predicate} 9788and @code{Static_Predicate} except that whether the resulting 9789predicate is static or dynamic is controlled by the form of the 9790expression. It is also separately controllable using pragma 9791@code{Assertion_Policy}. 9792 9793@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9794@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{148} 9795@section Aspect Pure_Function 9796 9797 9798@geindex Pure_Function 9799 9800This boolean aspect is equivalent to @ref{cc,,pragma Pure_Function}. 9801 9802@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9803@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{149} 9804@section Aspect Refined_Depends 9805 9806 9807@geindex Refined_Depends 9808 9809This aspect is equivalent to @ref{d0,,pragma Refined_Depends}. 9810 9811@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9812@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14a} 9813@section Aspect Refined_Global 9814 9815 9816@geindex Refined_Global 9817 9818This aspect is equivalent to @ref{d2,,pragma Refined_Global}. 9819 9820@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9821@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14b} 9822@section Aspect Refined_Post 9823 9824 9825@geindex Refined_Post 9826 9827This aspect is equivalent to @ref{d4,,pragma Refined_Post}. 9828 9829@node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects 9830@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14c} 9831@section Aspect Refined_State 9832 9833 9834@geindex Refined_State 9835 9836This aspect is equivalent to @ref{d6,,pragma Refined_State}. 9837 9838@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Refined_State,Implementation Defined Aspects 9839@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14d} 9840@section Aspect Remote_Access_Type 9841 9842 9843@geindex Remote_Access_Type 9844 9845This aspect is equivalent to @ref{da,,pragma Remote_Access_Type}. 9846 9847@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects 9848@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14e} 9849@section Aspect Secondary_Stack_Size 9850 9851 9852@geindex Secondary_Stack_Size 9853 9854This aspect is equivalent to @ref{df,,pragma Secondary_Stack_Size}. 9855 9856@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects 9857@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14f} 9858@section Aspect Scalar_Storage_Order 9859 9860 9861@geindex Scalar_Storage_Order 9862 9863This aspect is equivalent to a @ref{150,,attribute Scalar_Storage_Order}. 9864 9865@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 9866@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{151} 9867@section Aspect Shared 9868 9869 9870@geindex Shared 9871 9872This boolean aspect is equivalent to @ref{e2,,pragma Shared} 9873and is thus a synonym for aspect @code{Atomic}. 9874 9875@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 9876@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{152} 9877@section Aspect Simple_Storage_Pool 9878 9879 9880@geindex Simple_Storage_Pool 9881 9882This aspect is equivalent to @ref{e7,,attribute Simple_Storage_Pool}. 9883 9884@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 9885@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{153} 9886@section Aspect Simple_Storage_Pool_Type 9887 9888 9889@geindex Simple_Storage_Pool_Type 9890 9891This boolean aspect is equivalent to @ref{e5,,pragma Simple_Storage_Pool_Type}. 9892 9893@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 9894@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{154} 9895@section Aspect SPARK_Mode 9896 9897 9898@geindex SPARK_Mode 9899 9900This aspect is equivalent to @ref{ed,,pragma SPARK_Mode} and 9901may be specified for either or both of the specification and body 9902of a subprogram or package. 9903 9904@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 9905@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{155} 9906@section Aspect Suppress_Debug_Info 9907 9908 9909@geindex Suppress_Debug_Info 9910 9911This boolean aspect is equivalent to @ref{f5,,pragma Suppress_Debug_Info}. 9912 9913@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 9914@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{156} 9915@section Aspect Suppress_Initialization 9916 9917 9918@geindex Suppress_Initialization 9919 9920This boolean aspect is equivalent to @ref{f9,,pragma Suppress_Initialization}. 9921 9922@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 9923@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{157} 9924@section Aspect Test_Case 9925 9926 9927@geindex Test_Case 9928 9929This aspect is equivalent to @ref{fc,,pragma Test_Case}. 9930 9931@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 9932@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{158} 9933@section Aspect Thread_Local_Storage 9934 9935 9936@geindex Thread_Local_Storage 9937 9938This boolean aspect is equivalent to @ref{fe,,pragma Thread_Local_Storage}. 9939 9940@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects 9941@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{159} 9942@section Aspect Universal_Aliasing 9943 9944 9945@geindex Universal_Aliasing 9946 9947This boolean aspect is equivalent to @ref{109,,pragma Universal_Aliasing}. 9948 9949@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects 9950@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{15a} 9951@section Aspect Universal_Data 9952 9953 9954@geindex Universal_Data 9955 9956This aspect is equivalent to @ref{10a,,pragma Universal_Data}. 9957 9958@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects 9959@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15b} 9960@section Aspect Unmodified 9961 9962 9963@geindex Unmodified 9964 9965This boolean aspect is equivalent to @ref{10c,,pragma Unmodified}. 9966 9967@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 9968@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15c} 9969@section Aspect Unreferenced 9970 9971 9972@geindex Unreferenced 9973 9974This boolean aspect is equivalent to @ref{10e,,pragma Unreferenced}. Note that 9975in the case of formal parameters, it is not permitted to have aspects for 9976a formal parameter, so in this case the pragma form must be used. 9977 9978@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 9979@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15d} 9980@section Aspect Unreferenced_Objects 9981 9982 9983@geindex Unreferenced_Objects 9984 9985This boolean aspect is equivalent to @ref{110,,pragma Unreferenced_Objects}. 9986 9987@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 9988@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15e} 9989@section Aspect Value_Size 9990 9991 9992@geindex Value_Size 9993 9994This aspect is equivalent to @ref{15f,,attribute Value_Size}. 9995 9996@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 9997@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{160} 9998@section Aspect Volatile_Full_Access 9999 10000 10001@geindex Volatile_Full_Access 10002 10003This boolean aspect is equivalent to @ref{119,,pragma Volatile_Full_Access}. 10004 10005@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 10006@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{161} 10007@section Aspect Volatile_Function 10008 10009 10010@geindex Volatile_Function 10011 10012This boolean aspect is equivalent to @ref{11c,,pragma Volatile_Function}. 10013 10014@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 10015@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{162} 10016@section Aspect Warnings 10017 10018 10019@geindex Warnings 10020 10021This aspect is equivalent to the two argument form of @ref{11e,,pragma Warnings}, 10022where the first argument is @code{ON} or @code{OFF} and the second argument 10023is the entity. 10024 10025@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 10026@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{163}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{164} 10027@chapter Implementation Defined Attributes 10028 10029 10030Ada defines (throughout the Ada reference manual, 10031summarized in Annex K), 10032a set of attributes that provide useful additional functionality in all 10033areas of the language. These language defined attributes are implemented 10034in GNAT and work as described in the Ada Reference Manual. 10035 10036In addition, Ada allows implementations to define additional 10037attributes whose meaning is defined by the implementation. GNAT provides 10038a number of these implementation-dependent attributes which can be used 10039to extend and enhance the functionality of the compiler. This section of 10040the GNAT reference manual describes these additional attributes. It also 10041describes additional implementation-dependent features of standard 10042language-defined attributes. 10043 10044Note that any program using these attributes may not be portable to 10045other compilers (although GNAT implements this set of attributes on all 10046platforms). Therefore if portability to other compilers is an important 10047consideration, you should minimize the use of these attributes. 10048 10049@menu 10050* Attribute Abort_Signal:: 10051* Attribute Address_Size:: 10052* Attribute Asm_Input:: 10053* Attribute Asm_Output:: 10054* Attribute Atomic_Always_Lock_Free:: 10055* Attribute Bit:: 10056* Attribute Bit_Position:: 10057* Attribute Code_Address:: 10058* Attribute Compiler_Version:: 10059* Attribute Constrained:: 10060* Attribute Default_Bit_Order:: 10061* Attribute Default_Scalar_Storage_Order:: 10062* Attribute Deref:: 10063* Attribute Descriptor_Size:: 10064* Attribute Elaborated:: 10065* Attribute Elab_Body:: 10066* Attribute Elab_Spec:: 10067* Attribute Elab_Subp_Body:: 10068* Attribute Emax:: 10069* Attribute Enabled:: 10070* Attribute Enum_Rep:: 10071* Attribute Enum_Val:: 10072* Attribute Epsilon:: 10073* Attribute Fast_Math:: 10074* Attribute Finalization_Size:: 10075* Attribute Fixed_Value:: 10076* Attribute From_Any:: 10077* Attribute Has_Access_Values:: 10078* Attribute Has_Discriminants:: 10079* Attribute Img:: 10080* Attribute Integer_Value:: 10081* Attribute Invalid_Value:: 10082* Attribute Iterable:: 10083* Attribute Large:: 10084* Attribute Library_Level:: 10085* Attribute Lock_Free:: 10086* Attribute Loop_Entry:: 10087* Attribute Machine_Size:: 10088* Attribute Mantissa:: 10089* Attribute Maximum_Alignment:: 10090* Attribute Mechanism_Code:: 10091* Attribute Null_Parameter:: 10092* Attribute Object_Size:: 10093* Attribute Old:: 10094* Attribute Passed_By_Reference:: 10095* Attribute Pool_Address:: 10096* Attribute Range_Length:: 10097* Attribute Restriction_Set:: 10098* Attribute Result:: 10099* Attribute Safe_Emax:: 10100* Attribute Safe_Large:: 10101* Attribute Safe_Small:: 10102* Attribute Scalar_Storage_Order:: 10103* Attribute Simple_Storage_Pool:: 10104* Attribute Small:: 10105* Attribute Storage_Unit:: 10106* Attribute Stub_Type:: 10107* Attribute System_Allocator_Alignment:: 10108* Attribute Target_Name:: 10109* Attribute To_Address:: 10110* Attribute To_Any:: 10111* Attribute Type_Class:: 10112* Attribute Type_Key:: 10113* Attribute TypeCode:: 10114* Attribute Unconstrained_Array:: 10115* Attribute Universal_Literal_String:: 10116* Attribute Unrestricted_Access:: 10117* Attribute Update:: 10118* Attribute Valid_Scalars:: 10119* Attribute VADS_Size:: 10120* Attribute Value_Size:: 10121* Attribute Wchar_T_Size:: 10122* Attribute Word_Size:: 10123 10124@end menu 10125 10126@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 10127@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{165} 10128@section Attribute Abort_Signal 10129 10130 10131@geindex Abort_Signal 10132 10133@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 10134prefix) provides the entity for the special exception used to signal 10135task abort or asynchronous transfer of control. Normally this attribute 10136should only be used in the tasking runtime (it is highly peculiar, and 10137completely outside the normal semantics of Ada, for a user program to 10138intercept the abort exception). 10139 10140@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 10141@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{166} 10142@section Attribute Address_Size 10143 10144 10145@geindex Size of `@w{`}Address`@w{`} 10146 10147@geindex Address_Size 10148 10149@code{Standard'Address_Size} (@code{Standard} is the only allowed 10150prefix) is a static constant giving the number of bits in an 10151@code{Address}. It is the same value as System.Address'Size, 10152but has the advantage of being static, while a direct 10153reference to System.Address'Size is nonstatic because Address 10154is a private type. 10155 10156@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 10157@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{167} 10158@section Attribute Asm_Input 10159 10160 10161@geindex Asm_Input 10162 10163The @code{Asm_Input} attribute denotes a function that takes two 10164parameters. The first is a string, the second is an expression of the 10165type designated by the prefix. The first (string) argument is required 10166to be a static expression, and is the constraint for the parameter, 10167(e.g., what kind of register is required). The second argument is the 10168value to be used as the input argument. The possible values for the 10169constant are the same as those used in the RTL, and are dependent on 10170the configuration file used to built the GCC back end. 10171@ref{168,,Machine Code Insertions} 10172 10173@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 10174@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{169} 10175@section Attribute Asm_Output 10176 10177 10178@geindex Asm_Output 10179 10180The @code{Asm_Output} attribute denotes a function that takes two 10181parameters. The first is a string, the second is the name of a variable 10182of the type designated by the attribute prefix. The first (string) 10183argument is required to be a static expression and designates the 10184constraint for the parameter (e.g., what kind of register is 10185required). The second argument is the variable to be updated with the 10186result. The possible values for constraint are the same as those used in 10187the RTL, and are dependent on the configuration file used to build the 10188GCC back end. If there are no output operands, then this argument may 10189either be omitted, or explicitly given as @code{No_Output_Operands}. 10190@ref{168,,Machine Code Insertions} 10191 10192@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 10193@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16a} 10194@section Attribute Atomic_Always_Lock_Free 10195 10196 10197@geindex Atomic_Always_Lock_Free 10198 10199The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. 10200The result is a Boolean value which is True if the type has discriminants, 10201and False otherwise. The result indicate whether atomic operations are 10202supported by the target for the given type. 10203 10204@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 10205@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16b} 10206@section Attribute Bit 10207 10208 10209@geindex Bit 10210 10211@code{obj'Bit}, where @code{obj} is any object, yields the bit 10212offset within the storage unit (byte) that contains the first bit of 10213storage allocated for the object. The value of this attribute is of the 10214type @emph{universal_integer}, and is always a non-negative number not 10215exceeding the value of @code{System.Storage_Unit}. 10216 10217For an object that is a variable or a constant allocated in a register, 10218the value is zero. (The use of this attribute does not force the 10219allocation of a variable to memory). 10220 10221For an object that is a formal parameter, this attribute applies 10222to either the matching actual parameter or to a copy of the 10223matching actual parameter. 10224 10225For an access object the value is zero. Note that 10226@code{obj.all'Bit} is subject to an @code{Access_Check} for the 10227designated object. Similarly for a record component 10228@code{X.C'Bit} is subject to a discriminant check and 10229@code{X(I).Bit} and @code{X(I1..I2)'Bit} 10230are subject to index checks. 10231 10232This attribute is designed to be compatible with the DEC Ada 83 definition 10233and implementation of the @code{Bit} attribute. 10234 10235@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 10236@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16c} 10237@section Attribute Bit_Position 10238 10239 10240@geindex Bit_Position 10241 10242@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one 10243of the fields of the record type, yields the bit 10244offset within the record contains the first bit of 10245storage allocated for the object. The value of this attribute is of the 10246type @emph{universal_integer}. The value depends only on the field 10247@code{C} and is independent of the alignment of 10248the containing record @code{R}. 10249 10250@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 10251@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16d} 10252@section Attribute Code_Address 10253 10254 10255@geindex Code_Address 10256 10257@geindex Subprogram address 10258 10259@geindex Address of subprogram code 10260 10261The @code{'Address} 10262attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 10263intended effect seems to be to provide 10264an address value which can be used to call the subprogram by means of 10265an address clause as in the following example: 10266 10267@example 10268procedure K is ... 10269 10270procedure L; 10271for L'Address use K'Address; 10272pragma Import (Ada, L); 10273@end example 10274 10275A call to @code{L} is then expected to result in a call to @code{K}. 10276In Ada 83, where there were no access-to-subprogram values, this was 10277a common work-around for getting the effect of an indirect call. 10278GNAT implements the above use of @code{Address} and the technique 10279illustrated by the example code works correctly. 10280 10281However, for some purposes, it is useful to have the address of the start 10282of the generated code for the subprogram. On some architectures, this is 10283not necessarily the same as the @code{Address} value described above. 10284For example, the @code{Address} value may reference a subprogram 10285descriptor rather than the subprogram itself. 10286 10287The @code{'Code_Address} attribute, which can only be applied to 10288subprogram entities, always returns the address of the start of the 10289generated code of the specified subprogram, which may or may not be 10290the same value as is returned by the corresponding @code{'Address} 10291attribute. 10292 10293@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 10294@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16e} 10295@section Attribute Compiler_Version 10296 10297 10298@geindex Compiler_Version 10299 10300@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 10301prefix) yields a static string identifying the version of the compiler 10302being used to compile the unit containing the attribute reference. 10303 10304@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 10305@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16f} 10306@section Attribute Constrained 10307 10308 10309@geindex Constrained 10310 10311In addition to the usage of this attribute in the Ada RM, GNAT 10312also permits the use of the @code{'Constrained} attribute 10313in a generic template 10314for any type, including types without discriminants. The value of this 10315attribute in the generic instance when applied to a scalar type or a 10316record type without discriminants is always @code{True}. This usage is 10317compatible with older Ada compilers, including notably DEC Ada. 10318 10319@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 10320@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{170} 10321@section Attribute Default_Bit_Order 10322 10323 10324@geindex Big endian 10325 10326@geindex Little endian 10327 10328@geindex Default_Bit_Order 10329 10330@code{Standard'Default_Bit_Order} (@code{Standard} is the only 10331permissible prefix), provides the value @code{System.Default_Bit_Order} 10332as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 10333@code{Low_Order_First}). This is used to construct the definition of 10334@code{Default_Bit_Order} in package @code{System}. 10335 10336@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 10337@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{171} 10338@section Attribute Default_Scalar_Storage_Order 10339 10340 10341@geindex Big endian 10342 10343@geindex Little endian 10344 10345@geindex Default_Scalar_Storage_Order 10346 10347@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only 10348permissible prefix), provides the current value of the default scalar storage 10349order (as specified using pragma @code{Default_Scalar_Storage_Order}, or 10350equal to @code{Default_Bit_Order} if unspecified) as a 10351@code{System.Bit_Order} value. This is a static attribute. 10352 10353@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 10354@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{172} 10355@section Attribute Deref 10356 10357 10358@geindex Deref 10359 10360The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields 10361the variable of type @code{typ} that is located at the given address. It is similar 10362to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to 10363a named access-to-@cite{typ} type, except that it yields a variable, so it can be 10364used on the left side of an assignment. 10365 10366@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 10367@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{173} 10368@section Attribute Descriptor_Size 10369 10370 10371@geindex Descriptor 10372 10373@geindex Dope vector 10374 10375@geindex Descriptor_Size 10376 10377Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the 10378descriptor allocated for a type. The result is non-zero only for unconstrained 10379array types and the returned value is of type universal integer. In GNAT, an 10380array descriptor contains bounds information and is located immediately before 10381the first element of the array. 10382 10383@example 10384type Unconstr_Array is array (Positive range <>) of Boolean; 10385Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 10386@end example 10387 10388The attribute takes into account any additional padding due to type alignment. 10389In the example above, the descriptor contains two values of type 10390@code{Positive} representing the low and high bound. Since @code{Positive} has 10391a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * Positive'Size + 2} or 64 bits. 10392 10393@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 10394@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{174} 10395@section Attribute Elaborated 10396 10397 10398@geindex Elaborated 10399 10400The prefix of the @code{'Elaborated} attribute must be a unit name. The 10401value is a Boolean which indicates whether or not the given unit has been 10402elaborated. This attribute is primarily intended for internal use by the 10403generated code for dynamic elaboration checking, but it can also be used 10404in user programs. The value will always be True once elaboration of all 10405units has been completed. An exception is for units which need no 10406elaboration, the value is always False for such units. 10407 10408@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 10409@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{175} 10410@section Attribute Elab_Body 10411 10412 10413@geindex Elab_Body 10414 10415This attribute can only be applied to a program unit name. It returns 10416the entity for the corresponding elaboration procedure for elaborating 10417the body of the referenced unit. This is used in the main generated 10418elaboration procedure by the binder and is not normally used in any 10419other context. However, there may be specialized situations in which it 10420is useful to be able to call this elaboration procedure from Ada code, 10421e.g., if it is necessary to do selective re-elaboration to fix some 10422error. 10423 10424@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 10425@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{176} 10426@section Attribute Elab_Spec 10427 10428 10429@geindex Elab_Spec 10430 10431This attribute can only be applied to a program unit name. It returns 10432the entity for the corresponding elaboration procedure for elaborating 10433the spec of the referenced unit. This is used in the main 10434generated elaboration procedure by the binder and is not normally used 10435in any other context. However, there may be specialized situations in 10436which it is useful to be able to call this elaboration procedure from 10437Ada code, e.g., if it is necessary to do selective re-elaboration to fix 10438some error. 10439 10440@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 10441@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{177} 10442@section Attribute Elab_Subp_Body 10443 10444 10445@geindex Elab_Subp_Body 10446 10447This attribute can only be applied to a library level subprogram 10448name and is only allowed in CodePeer mode. It returns the entity 10449for the corresponding elaboration procedure for elaborating the body 10450of the referenced subprogram unit. This is used in the main generated 10451elaboration procedure by the binder in CodePeer mode only and is unrecognized 10452otherwise. 10453 10454@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 10455@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{178} 10456@section Attribute Emax 10457 10458 10459@geindex Ada 83 attributes 10460 10461@geindex Emax 10462 10463The @code{Emax} attribute is provided for compatibility with Ada 83. See 10464the Ada 83 reference manual for an exact description of the semantics of 10465this attribute. 10466 10467@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 10468@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{179} 10469@section Attribute Enabled 10470 10471 10472@geindex Enabled 10473 10474The @code{Enabled} attribute allows an application program to check at compile 10475time to see if the designated check is currently enabled. The prefix is a 10476simple identifier, referencing any predefined check name (other than 10477@code{All_Checks}) or a check name introduced by pragma Check_Name. If 10478no argument is given for the attribute, the check is for the general state 10479of the check, if an argument is given, then it is an entity name, and the 10480check indicates whether an @code{Suppress} or @code{Unsuppress} has been 10481given naming the entity (if not, then the argument is ignored). 10482 10483Note that instantiations inherit the check status at the point of the 10484instantiation, so a useful idiom is to have a library package that 10485introduces a check name with @code{pragma Check_Name}, and then contains 10486generic packages or subprograms which use the @code{Enabled} attribute 10487to see if the check is enabled. A user of this package can then issue 10488a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 10489the package or subprogram, controlling whether the check will be present. 10490 10491@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 10492@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17a} 10493@section Attribute Enum_Rep 10494 10495 10496@geindex Representation of enums 10497 10498@geindex Enum_Rep 10499 10500For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a 10501function with the following spec: 10502 10503@example 10504function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 10505@end example 10506 10507It is also allowable to apply @code{Enum_Rep} directly to an object of an 10508enumeration type or to a non-overloaded enumeration 10509literal. In this case @code{S'Enum_Rep} is equivalent to 10510@code{typ'Enum_Rep(S)} where @code{typ} is the type of the 10511enumeration literal or object. 10512 10513The function returns the representation value for the given enumeration 10514value. This will be equal to value of the @code{Pos} attribute in the 10515absence of an enumeration representation clause. This is a static 10516attribute (i.e.,:the result is static if the argument is static). 10517 10518@code{S'Enum_Rep} can also be used with integer types and objects, 10519in which case it simply returns the integer value. The reason for this 10520is to allow it to be used for @code{(<>)} discrete formal arguments in 10521a generic unit that can be instantiated with either enumeration types 10522or integer types. Note that if @code{Enum_Rep} is used on a modular 10523type whose upper bound exceeds the upper bound of the largest signed 10524integer type, and the argument is a variable, so that the universal 10525integer calculation is done at run time, then the call to @code{Enum_Rep} 10526may raise @code{Constraint_Error}. 10527 10528@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 10529@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17b} 10530@section Attribute Enum_Val 10531 10532 10533@geindex Representation of enums 10534 10535@geindex Enum_Val 10536 10537For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a 10538function with the following spec: 10539 10540@example 10541function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 10542@end example 10543 10544The function returns the enumeration value whose representation matches the 10545argument, or raises Constraint_Error if no enumeration literal of the type 10546has the matching value. 10547This will be equal to value of the @code{Val} attribute in the 10548absence of an enumeration representation clause. This is a static 10549attribute (i.e., the result is static if the argument is static). 10550 10551@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 10552@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17c} 10553@section Attribute Epsilon 10554 10555 10556@geindex Ada 83 attributes 10557 10558@geindex Epsilon 10559 10560The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 10561the Ada 83 reference manual for an exact description of the semantics of 10562this attribute. 10563 10564@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes 10565@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17d} 10566@section Attribute Fast_Math 10567 10568 10569@geindex Fast_Math 10570 10571@code{Standard'Fast_Math} (@code{Standard} is the only allowed 10572prefix) yields a static Boolean value that is True if pragma 10573@code{Fast_Math} is active, and False otherwise. 10574 10575@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes 10576@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17e} 10577@section Attribute Finalization_Size 10578 10579 10580@geindex Finalization_Size 10581 10582The prefix of attribute @code{Finalization_Size} must be an object or 10583a non-class-wide type. This attribute returns the size of any hidden data 10584reserved by the compiler to handle finalization-related actions. The type of 10585the attribute is @emph{universal_integer}. 10586 10587@code{Finalization_Size} yields a value of zero for a type with no controlled 10588parts, an object whose type has no controlled parts, or an object of a 10589class-wide type whose tag denotes a type with no controlled parts. 10590 10591Note that only heap-allocated objects contain finalization data. 10592 10593@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes 10594@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17f} 10595@section Attribute Fixed_Value 10596 10597 10598@geindex Fixed_Value 10599 10600For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a 10601function with the following specification: 10602 10603@example 10604function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10605@end example 10606 10607The value returned is the fixed-point value @code{V} such that: 10608 10609@example 10610V = Arg * S'Small 10611@end example 10612 10613The effect is thus similar to first converting the argument to the 10614integer type used to represent @code{S}, and then doing an unchecked 10615conversion to the fixed-point type. The difference is 10616that there are full range checks, to ensure that the result is in range. 10617This attribute is primarily intended for use in implementation of the 10618input-output functions for fixed-point values. 10619 10620@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10621@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{180} 10622@section Attribute From_Any 10623 10624 10625@geindex From_Any 10626 10627This internal attribute is used for the generation of remote subprogram 10628stubs in the context of the Distributed Systems Annex. 10629 10630@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10631@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{181} 10632@section Attribute Has_Access_Values 10633 10634 10635@geindex Access values 10636@geindex testing for 10637 10638@geindex Has_Access_Values 10639 10640The prefix of the @code{Has_Access_Values} attribute is a type. The result 10641is a Boolean value which is True if the is an access type, or is a composite 10642type with a component (at any nesting depth) that is an access type, and is 10643False otherwise. 10644The intended use of this attribute is in conjunction with generic 10645definitions. If the attribute is applied to a generic private type, it 10646indicates whether or not the corresponding actual type has access values. 10647 10648@node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes 10649@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{182} 10650@section Attribute Has_Discriminants 10651 10652 10653@geindex Discriminants 10654@geindex testing for 10655 10656@geindex Has_Discriminants 10657 10658The prefix of the @code{Has_Discriminants} attribute is a type. The result 10659is a Boolean value which is True if the type has discriminants, and False 10660otherwise. The intended use of this attribute is in conjunction with generic 10661definitions. If the attribute is applied to a generic private type, it 10662indicates whether or not the corresponding actual type has discriminants. 10663 10664@node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes 10665@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{183} 10666@section Attribute Img 10667 10668 10669@geindex Img 10670 10671The @code{Img} attribute differs from @code{Image} in that it is applied 10672directly to an object, and yields the same result as 10673@code{Image} for the subtype of the object. This is convenient for 10674debugging: 10675 10676@example 10677Put_Line ("X = " & X'Img); 10678@end example 10679 10680has the same meaning as the more verbose: 10681 10682@example 10683Put_Line ("X = " & T'Image (X)); 10684@end example 10685 10686where @code{T} is the (sub)type of the object @code{X}. 10687 10688Note that technically, in analogy to @code{Image}, 10689@code{X'Img} returns a parameterless function 10690that returns the appropriate string when called. This means that 10691@code{X'Img} can be renamed as a function-returning-string, or used 10692in an instantiation as a function parameter. 10693 10694@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes 10695@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{184} 10696@section Attribute Integer_Value 10697 10698 10699@geindex Integer_Value 10700 10701For every integer type @code{S}, @code{S'Integer_Value} denotes a 10702function with the following spec: 10703 10704@example 10705function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10706@end example 10707 10708The value returned is the integer value @code{V}, such that: 10709 10710@example 10711Arg = V * T'Small 10712@end example 10713 10714where @code{T} is the type of @code{Arg}. 10715The effect is thus similar to first doing an unchecked conversion from 10716the fixed-point type to its corresponding implementation type, and then 10717converting the result to the target integer type. The difference is 10718that there are full range checks, to ensure that the result is in range. 10719This attribute is primarily intended for use in implementation of the 10720standard input-output functions for fixed-point values. 10721 10722@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10723@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{185} 10724@section Attribute Invalid_Value 10725 10726 10727@geindex Invalid_Value 10728 10729For every scalar type S, S'Invalid_Value returns an undefined value of the 10730type. If possible this value is an invalid representation for the type. The 10731value returned is identical to the value used to initialize an otherwise 10732uninitialized value of the type if pragma Initialize_Scalars is used, 10733including the ability to modify the value with the binder -Sxx flag and 10734relevant environment variables at run time. 10735 10736@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10737@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{186} 10738@section Attribute Iterable 10739 10740 10741@geindex Iterable 10742 10743Equivalent to Aspect Iterable. 10744 10745@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10746@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{187} 10747@section Attribute Large 10748 10749 10750@geindex Ada 83 attributes 10751 10752@geindex Large 10753 10754The @code{Large} attribute is provided for compatibility with Ada 83. See 10755the Ada 83 reference manual for an exact description of the semantics of 10756this attribute. 10757 10758@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10759@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{188} 10760@section Attribute Library_Level 10761 10762 10763@geindex Library_Level 10764 10765@code{P'Library_Level}, where P is an entity name, 10766returns a Boolean value which is True if the entity is declared 10767at the library level, and False otherwise. Note that within a 10768generic instantition, the name of the generic unit denotes the 10769instance, which means that this attribute can be used to test 10770if a generic is instantiated at the library level, as shown 10771in this example: 10772 10773@example 10774generic 10775 ... 10776package Gen is 10777 pragma Compile_Time_Error 10778 (not Gen'Library_Level, 10779 "Gen can only be instantiated at library level"); 10780 ... 10781end Gen; 10782@end example 10783 10784@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10785@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{189} 10786@section Attribute Lock_Free 10787 10788 10789@geindex Lock_Free 10790 10791@code{P'Lock_Free}, where P is a protected object, returns True if a 10792pragma @code{Lock_Free} applies to P. 10793 10794@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 10795@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18a} 10796@section Attribute Loop_Entry 10797 10798 10799@geindex Loop_Entry 10800 10801Syntax: 10802 10803@example 10804X'Loop_Entry [(loop_name)] 10805@end example 10806 10807The @code{Loop_Entry} attribute is used to refer to the value that an 10808expression had upon entry to a given loop in much the same way that the 10809@code{Old} attribute in a subprogram postcondition can be used to refer 10810to the value an expression had upon entry to the subprogram. The 10811relevant loop is either identified by the given loop name, or it is the 10812innermost enclosing loop when no loop name is given. 10813 10814A @code{Loop_Entry} attribute can only occur within a 10815@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 10816@code{Loop_Entry} is to compare the current value of objects with their 10817initial value at loop entry, in a @code{Loop_Invariant} pragma. 10818 10819The effect of using @code{X'Loop_Entry} is the same as declaring 10820a constant initialized with the initial value of @code{X} at loop 10821entry. This copy is not performed if the loop is not entered, or if the 10822corresponding pragmas are ignored or disabled. 10823 10824@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 10825@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18b} 10826@section Attribute Machine_Size 10827 10828 10829@geindex Machine_Size 10830 10831This attribute is identical to the @code{Object_Size} attribute. It is 10832provided for compatibility with the DEC Ada 83 attribute of this name. 10833 10834@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 10835@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18c} 10836@section Attribute Mantissa 10837 10838 10839@geindex Ada 83 attributes 10840 10841@geindex Mantissa 10842 10843The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 10844the Ada 83 reference manual for an exact description of the semantics of 10845this attribute. 10846 10847@node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes 10848@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18d}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18e} 10849@section Attribute Maximum_Alignment 10850 10851 10852@geindex Alignment 10853@geindex maximum 10854 10855@geindex Maximum_Alignment 10856 10857@code{Standard'Maximum_Alignment} (@code{Standard} is the only 10858permissible prefix) provides the maximum useful alignment value for the 10859target. This is a static value that can be used to specify the alignment 10860for an object, guaranteeing that it is properly aligned in all 10861cases. 10862 10863@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes 10864@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18f} 10865@section Attribute Mechanism_Code 10866 10867 10868@geindex Return values 10869@geindex passing mechanism 10870 10871@geindex Parameters 10872@geindex passing mechanism 10873 10874@geindex Mechanism_Code 10875 10876@code{func'Mechanism_Code} yields an integer code for the 10877mechanism used for the result of function @code{func}, and 10878@code{subprog'Mechanism_Code (n)} yields the mechanism 10879used for formal parameter number @emph{n} (a static integer value, with 1 10880meaning the first parameter) of subprogram @code{subprog}. The code returned is: 10881 10882 10883@table @asis 10884 10885@item @emph{1} 10886 10887by copy (value) 10888 10889@item @emph{2} 10890 10891by reference 10892@end table 10893 10894@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 10895@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{190} 10896@section Attribute Null_Parameter 10897 10898 10899@geindex Zero address 10900@geindex passing 10901 10902@geindex Null_Parameter 10903 10904A reference @code{T'Null_Parameter} denotes an imaginary object of 10905type or subtype @code{T} allocated at machine address zero. The attribute 10906is allowed only as the default expression of a formal parameter, or as 10907an actual expression of a subprogram call. In either case, the 10908subprogram must be imported. 10909 10910The identity of the object is represented by the address zero in the 10911argument list, independent of the passing mechanism (explicit or 10912default). 10913 10914This capability is needed to specify that a zero address should be 10915passed for a record or other composite object passed by reference. 10916There is no way of indicating this without the @code{Null_Parameter} 10917attribute. 10918 10919@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 10920@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{143}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{191} 10921@section Attribute Object_Size 10922 10923 10924@geindex Size 10925@geindex used for objects 10926 10927@geindex Object_Size 10928 10929The size of an object is not necessarily the same as the size of the type 10930of an object. This is because by default object sizes are increased to be 10931a multiple of the alignment of the object. For example, 10932@code{Natural'Size} is 1093331, but by default objects of type @code{Natural} will have a size of 32 bits. 10934Similarly, a record containing an integer and a character: 10935 10936@example 10937type Rec is record 10938 I : Integer; 10939 C : Character; 10940end record; 10941@end example 10942 10943will have a size of 40 (that is @code{Rec'Size} will be 40). The 10944alignment will be 4, because of the 10945integer field, and so the default size of record objects for this type 10946will be 64 (8 bytes). 10947 10948If the alignment of the above record is specified to be 1, then the 10949object size will be 40 (5 bytes). This is true by default, and also 10950an object size of 40 can be explicitly specified in this case. 10951 10952A consequence of this capability is that different object sizes can be 10953given to subtypes that would otherwise be considered in Ada to be 10954statically matching. But it makes no sense to consider such subtypes 10955as statically matching. Consequently, GNAT adds a rule 10956to the static matching rules that requires object sizes to match. 10957Consider this example: 10958 10959@example 10960 1. procedure BadAVConvert is 10961 2. type R is new Integer; 10962 3. subtype R1 is R range 1 .. 10; 10963 4. subtype R2 is R range 1 .. 10; 10964 5. for R1'Object_Size use 8; 10965 6. for R2'Object_Size use 16; 10966 7. type R1P is access all R1; 10967 8. type R2P is access all R2; 10968 9. R1PV : R1P := new R1'(4); 1096910. R2PV : R2P; 1097011. begin 1097112. R2PV := R2P (R1PV); 10972 | 10973 >>> target designated subtype not compatible with 10974 type "R1" defined at line 3 10975 1097613. end; 10977@end example 10978 10979In the absence of lines 5 and 6, 10980types @code{R1} and @code{R2} statically match and 10981hence the conversion on line 12 is legal. But since lines 5 and 6 10982cause the object sizes to differ, GNAT considers that types 10983@code{R1} and @code{R2} are not statically matching, and line 12 10984generates the diagnostic shown above. 10985 10986Similar additional checks are performed in other contexts requiring 10987statically matching subtypes. 10988 10989@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 10990@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{192} 10991@section Attribute Old 10992 10993 10994@geindex Old 10995 10996In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage 10997within @code{Post} aspect), GNAT also permits the use of this attribute 10998in implementation defined pragmas @code{Postcondition}, 10999@code{Contract_Cases} and @code{Test_Case}. Also usages of 11000@code{Old} which would be illegal according to the Ada 2012 RM 11001definition are allowed under control of 11002implementation defined pragma @code{Unevaluated_Use_Of_Old}. 11003 11004@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 11005@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{193} 11006@section Attribute Passed_By_Reference 11007 11008 11009@geindex Parameters 11010@geindex when passed by reference 11011 11012@geindex Passed_By_Reference 11013 11014@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns 11015a value of type @code{Boolean} value that is @code{True} if the type is 11016normally passed by reference and @code{False} if the type is normally 11017passed by copy in calls. For scalar types, the result is always @code{False} 11018and is static. For non-scalar types, the result is nonstatic. 11019 11020@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 11021@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{194} 11022@section Attribute Pool_Address 11023 11024 11025@geindex Parameters 11026@geindex when passed by reference 11027 11028@geindex Pool_Address 11029 11030@code{X'Pool_Address} for any object @code{X} returns the address 11031of X within its storage pool. This is the same as 11032@code{X'Address}, except that for an unconstrained array whose 11033bounds are allocated just before the first component, 11034@code{X'Pool_Address} returns the address of those bounds, 11035whereas @code{X'Address} returns the address of the first 11036component. 11037 11038Here, we are interpreting 'storage pool' broadly to mean 11039@code{wherever the object is allocated}, which could be a 11040user-defined storage pool, 11041the global heap, on the stack, or in a static memory area. 11042For an object created by @code{new}, @code{Ptr.all'Pool_Address} is 11043what is passed to @code{Allocate} and returned from @code{Deallocate}. 11044 11045@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 11046@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{195} 11047@section Attribute Range_Length 11048 11049 11050@geindex Range_Length 11051 11052@code{typ'Range_Length} for any discrete type @cite{typ} yields 11053the number of values represented by the subtype (zero for a null 11054range). The result is static for static subtypes. @code{Range_Length} 11055applied to the index subtype of a one dimensional array always gives the 11056same result as @code{Length} applied to the array itself. 11057 11058@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 11059@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{196} 11060@section Attribute Restriction_Set 11061 11062 11063@geindex Restriction_Set 11064 11065@geindex Restrictions 11066 11067This attribute allows compile time testing of restrictions that 11068are currently in effect. It is primarily intended for specializing 11069code in the run-time based on restrictions that are active (e.g. 11070don't need to save fpt registers if restriction No_Floating_Point 11071is known to be in effect), but can be used anywhere. 11072 11073There are two forms: 11074 11075@example 11076System'Restriction_Set (partition_boolean_restriction_NAME) 11077System'Restriction_Set (No_Dependence => library_unit_NAME); 11078@end example 11079 11080In the case of the first form, the only restriction names 11081allowed are parameterless restrictions that are checked 11082for consistency at bind time. For a complete list see the 11083subtype @code{System.Rident.Partition_Boolean_Restrictions}. 11084 11085The result returned is True if the restriction is known to 11086be in effect, and False if the restriction is known not to 11087be in effect. An important guarantee is that the value of 11088a Restriction_Set attribute is known to be consistent throughout 11089all the code of a partition. 11090 11091This is trivially achieved if the entire partition is compiled 11092with a consistent set of restriction pragmas. However, the 11093compilation model does not require this. It is possible to 11094compile one set of units with one set of pragmas, and another 11095set of units with another set of pragmas. It is even possible 11096to compile a spec with one set of pragmas, and then WITH the 11097same spec with a different set of pragmas. Inconsistencies 11098in the actual use of the restriction are checked at bind time. 11099 11100In order to achieve the guarantee of consistency for the 11101Restriction_Set pragma, we consider that a use of the pragma 11102that yields False is equivalent to a violation of the 11103restriction. 11104 11105So for example if you write 11106 11107@example 11108if System'Restriction_Set (No_Floating_Point) then 11109 ... 11110else 11111 ... 11112end if; 11113@end example 11114 11115And the result is False, so that the else branch is executed, 11116you can assume that this restriction is not set for any unit 11117in the partition. This is checked by considering this use of 11118the restriction pragma to be a violation of the restriction 11119No_Floating_Point. This means that no other unit can attempt 11120to set this restriction (if some unit does attempt to set it, 11121the binder will refuse to bind the partition). 11122 11123Technical note: The restriction name and the unit name are 11124intepreted entirely syntactically, as in the corresponding 11125Restrictions pragma, they are not analyzed semantically, 11126so they do not have a type. 11127 11128@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 11129@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{197} 11130@section Attribute Result 11131 11132 11133@geindex Result 11134 11135@code{function'Result} can only be used with in a Postcondition pragma 11136for a function. The prefix must be the name of the corresponding function. This 11137is used to refer to the result of the function in the postcondition expression. 11138For a further discussion of the use of this attribute and examples of its use, 11139see the description of pragma Postcondition. 11140 11141@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 11142@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{198} 11143@section Attribute Safe_Emax 11144 11145 11146@geindex Ada 83 attributes 11147 11148@geindex Safe_Emax 11149 11150The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 11151the Ada 83 reference manual for an exact description of the semantics of 11152this attribute. 11153 11154@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 11155@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{199} 11156@section Attribute Safe_Large 11157 11158 11159@geindex Ada 83 attributes 11160 11161@geindex Safe_Large 11162 11163The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 11164the Ada 83 reference manual for an exact description of the semantics of 11165this attribute. 11166 11167@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 11168@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19a} 11169@section Attribute Safe_Small 11170 11171 11172@geindex Ada 83 attributes 11173 11174@geindex Safe_Small 11175 11176The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See 11177the Ada 83 reference manual for an exact description of the semantics of 11178this attribute. 11179 11180@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 11181@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19b}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{150} 11182@section Attribute Scalar_Storage_Order 11183 11184 11185@geindex Endianness 11186 11187@geindex Scalar storage order 11188 11189@geindex Scalar_Storage_Order 11190 11191For every array or record type @code{S}, the representation attribute 11192@code{Scalar_Storage_Order} denotes the order in which storage elements 11193that make up scalar components are ordered within S. The value given must 11194be a static expression of type System.Bit_Order. The following is an example 11195of the use of this feature: 11196 11197@example 11198-- Component type definitions 11199 11200subtype Yr_Type is Natural range 0 .. 127; 11201subtype Mo_Type is Natural range 1 .. 12; 11202subtype Da_Type is Natural range 1 .. 31; 11203 11204-- Record declaration 11205 11206type Date is record 11207 Years_Since_1980 : Yr_Type; 11208 Month : Mo_Type; 11209 Day_Of_Month : Da_Type; 11210end record; 11211 11212-- Record representation clause 11213 11214for Date use record 11215 Years_Since_1980 at 0 range 0 .. 6; 11216 Month at 0 range 7 .. 10; 11217 Day_Of_Month at 0 range 11 .. 15; 11218end record; 11219 11220-- Attribute definition clauses 11221 11222for Date'Bit_Order use System.High_Order_First; 11223for Date'Scalar_Storage_Order use System.High_Order_First; 11224-- If Scalar_Storage_Order is specified, it must be consistent with 11225-- Bit_Order, so it's best to always define the latter explicitly if 11226-- the former is used. 11227@end example 11228 11229Other properties are as for standard representation attribute @code{Bit_Order}, 11230as defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 11231 11232For a record type @code{T}, if @code{T'Scalar_Storage_Order} is 11233specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 11234this means that if a @code{Scalar_Storage_Order} attribute definition 11235clause is not confirming, then the type's @code{Bit_Order} shall be 11236specified explicitly and set to the same value. 11237 11238Derived types inherit an explicitly set scalar storage order from their parent 11239types. This may be overridden for the derived type by giving an explicit scalar 11240storage order for the derived type. For a record extension, the derived type 11241must have the same scalar storage order as the parent type. 11242 11243A component of a record type that is itself a record or an array and that does 11244not start and end on a byte boundary must have have the same scalar storage 11245order as the record type. A component of a bit-packed array type that is itself 11246a record or an array must have the same scalar storage order as the array type. 11247 11248No component of a type that has an explicit @code{Scalar_Storage_Order} 11249attribute definition may be aliased. 11250 11251A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 11252with a value equal to @code{System.Default_Bit_Order}) has no effect. 11253 11254If the opposite storage order is specified, then whenever the value of 11255a scalar component of an object of type @code{S} is read, the storage 11256elements of the enclosing machine scalar are first reversed (before 11257retrieving the component value, possibly applying some shift and mask 11258operatings on the enclosing machine scalar), and the opposite operation 11259is done for writes. 11260 11261In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 11262are relaxed. Instead, the following rules apply: 11263 11264 11265@itemize * 11266 11267@item 11268the underlying storage elements are those at positions 11269@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 11270 11271@item 11272the sequence of underlying storage elements shall have 11273a size no greater than the largest machine scalar 11274 11275@item 11276the enclosing machine scalar is defined as the smallest machine 11277scalar starting at a position no greater than 11278@code{position + first_bit / storage_element_size} and covering 11279storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} 11280 11281@item 11282the position of the component is interpreted relative to that machine 11283scalar. 11284@end itemize 11285 11286If no scalar storage order is specified for a type (either directly, or by 11287inheritance in the case of a derived type), then the default is normally 11288the native ordering of the target, but this default can be overridden using 11289pragma @code{Default_Scalar_Storage_Order}. 11290 11291Note that if a component of @code{T} is itself of a record or array type, 11292the specfied @code{Scalar_Storage_Order} does @emph{not} apply to that nested type: 11293an explicit attribute definition clause must be provided for the component 11294type as well if desired. 11295 11296Note that the scalar storage order only affects the in-memory data 11297representation. It has no effect on the representation used by stream 11298attributes. 11299 11300@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 11301@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e7}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19c} 11302@section Attribute Simple_Storage_Pool 11303 11304 11305@geindex Storage pool 11306@geindex simple 11307 11308@geindex Simple storage pool 11309 11310@geindex Simple_Storage_Pool 11311 11312For every nonformal, nonderived access-to-object type @code{Acc}, the 11313representation attribute @code{Simple_Storage_Pool} may be specified 11314via an attribute_definition_clause (or by specifying the equivalent aspect): 11315 11316@example 11317My_Pool : My_Simple_Storage_Pool_Type; 11318 11319type Acc is access My_Data_Type; 11320 11321for Acc'Simple_Storage_Pool use My_Pool; 11322@end example 11323 11324The name given in an attribute_definition_clause for the 11325@code{Simple_Storage_Pool} attribute shall denote a variable of 11326a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}). 11327 11328The use of this attribute is only allowed for a prefix denoting a type 11329for which it has been specified. The type of the attribute is the type 11330of the variable specified as the simple storage pool of the access type, 11331and the attribute denotes that variable. 11332 11333It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 11334for the same access type. 11335 11336If the @code{Simple_Storage_Pool} attribute has been specified for an access 11337type, then applying the @code{Storage_Pool} attribute to the type is flagged 11338with a warning and its evaluation raises the exception @code{Program_Error}. 11339 11340If the Simple_Storage_Pool attribute has been specified for an access 11341type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} 11342returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 11343which is intended to indicate the number of storage elements reserved for 11344the simple storage pool. If the Storage_Size function has not been defined 11345for the simple storage pool type, then this attribute returns zero. 11346 11347If an access type @code{S} has a specified simple storage pool of type 11348@code{SSP}, then the evaluation of an allocator for that access type calls 11349the primitive @code{Allocate} procedure for type @code{SSP}, passing 11350@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 11351semantics of such allocators is the same as those defined for allocators 11352in section 13.11 of the @cite{Ada Reference Manual}, with the term 11353@emph{simple storage pool} substituted for @emph{storage pool}. 11354 11355If an access type @code{S} has a specified simple storage pool of type 11356@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 11357for that access type invokes the primitive @code{Deallocate} procedure 11358for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 11359parameter. The detailed semantics of such unchecked deallocations is the same 11360as defined in section 13.11.2 of the Ada Reference Manual, except that the 11361term @emph{simple storage pool} is substituted for @emph{storage pool}. 11362 11363@node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes 11364@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19d} 11365@section Attribute Small 11366 11367 11368@geindex Ada 83 attributes 11369 11370@geindex Small 11371 11372The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 11373fixed-point types. 11374GNAT also allows this attribute to be applied to floating-point types 11375for compatibility with Ada 83. See 11376the Ada 83 reference manual for an exact description of the semantics of 11377this attribute when applied to floating-point types. 11378 11379@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes 11380@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{19e} 11381@section Attribute Storage_Unit 11382 11383 11384@geindex Storage_Unit 11385 11386@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 11387prefix) provides the same value as @code{System.Storage_Unit}. 11388 11389@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 11390@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{19f} 11391@section Attribute Stub_Type 11392 11393 11394@geindex Stub_Type 11395 11396The GNAT implementation of remote access-to-classwide types is 11397organized as described in AARM section E.4 (20.t): a value of an RACW type 11398(designating a remote object) is represented as a normal access 11399value, pointing to a "stub" object which in turn contains the 11400necessary information to contact the designated remote object. A 11401call on any dispatching operation of such a stub object does the 11402remote call, if necessary, using the information in the stub object 11403to locate the target partition, etc. 11404 11405For a prefix @code{T} that denotes a remote access-to-classwide type, 11406@code{T'Stub_Type} denotes the type of the corresponding stub objects. 11407 11408By construction, the layout of @code{T'Stub_Type} is identical to that of 11409type @code{RACW_Stub_Type} declared in the internal implementation-defined 11410unit @code{System.Partition_Interface}. Use of this attribute will create 11411an implicit dependency on this unit. 11412 11413@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 11414@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a0} 11415@section Attribute System_Allocator_Alignment 11416 11417 11418@geindex Alignment 11419@geindex allocator 11420 11421@geindex System_Allocator_Alignment 11422 11423@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 11424permissible prefix) provides the observable guaranted to be honored by 11425the system allocator (malloc). This is a static value that can be used 11426in user storage pools based on malloc either to reject allocation 11427with alignment too large or to enable a realignment circuitry if the 11428alignment request is larger than this value. 11429 11430@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 11431@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a1} 11432@section Attribute Target_Name 11433 11434 11435@geindex Target_Name 11436 11437@code{Standard'Target_Name} (@code{Standard} is the only permissible 11438prefix) provides a static string value that identifies the target 11439for the current compilation. For GCC implementations, this is the 11440standard gcc target name without the terminating slash (for 11441example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 11442 11443@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 11444@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a2} 11445@section Attribute To_Address 11446 11447 11448@geindex To_Address 11449 11450The @code{System'To_Address} 11451(@code{System} is the only permissible prefix) 11452denotes a function identical to 11453@code{System.Storage_Elements.To_Address} except that 11454it is a static attribute. This means that if its argument is 11455a static expression, then the result of the attribute is a 11456static expression. This means that such an expression can be 11457used in contexts (e.g., preelaborable packages) which require a 11458static expression and where the function call could not be used 11459(since the function call is always nonstatic, even if its 11460argument is static). The argument must be in the range 11461-(2**(m-1)) .. 2**m-1, where m is the memory size 11462(typically 32 or 64). Negative values are intepreted in a 11463modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 11464a 32 bits machine). 11465 11466@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 11467@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a3} 11468@section Attribute To_Any 11469 11470 11471@geindex To_Any 11472 11473This internal attribute is used for the generation of remote subprogram 11474stubs in the context of the Distributed Systems Annex. 11475 11476@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 11477@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a4} 11478@section Attribute Type_Class 11479 11480 11481@geindex Type_Class 11482 11483@code{typ'Type_Class} for any type or subtype @cite{typ} yields 11484the value of the type class for the full type of @cite{typ}. If 11485@cite{typ} is a generic formal type, the value is the value for the 11486corresponding actual subtype. The value of this attribute is of type 11487@code{System.Aux_DEC.Type_Class}, which has the following definition: 11488 11489@example 11490type Type_Class is 11491 (Type_Class_Enumeration, 11492 Type_Class_Integer, 11493 Type_Class_Fixed_Point, 11494 Type_Class_Floating_Point, 11495 Type_Class_Array, 11496 Type_Class_Record, 11497 Type_Class_Access, 11498 Type_Class_Task, 11499 Type_Class_Address); 11500@end example 11501 11502Protected types yield the value @code{Type_Class_Task}, which thus 11503applies to all concurrent types. This attribute is designed to 11504be compatible with the DEC Ada 83 attribute of the same name. 11505 11506@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 11507@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a5} 11508@section Attribute Type_Key 11509 11510 11511@geindex Type_Key 11512 11513The @code{Type_Key} attribute is applicable to a type or subtype and 11514yields a value of type Standard.String containing encoded information 11515about the type or subtype. This provides improved compatibility with 11516other implementations that support this attribute. 11517 11518@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 11519@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1a6} 11520@section Attribute TypeCode 11521 11522 11523@geindex TypeCode 11524 11525This internal attribute is used for the generation of remote subprogram 11526stubs in the context of the Distributed Systems Annex. 11527 11528@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 11529@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1a7} 11530@section Attribute Unconstrained_Array 11531 11532 11533@geindex Unconstrained_Array 11534 11535The @code{Unconstrained_Array} attribute can be used with a prefix that 11536denotes any type or subtype. It is a static attribute that yields 11537@code{True} if the prefix designates an unconstrained array, 11538and @code{False} otherwise. In a generic instance, the result is 11539still static, and yields the result of applying this test to the 11540generic actual. 11541 11542@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 11543@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1a8} 11544@section Attribute Universal_Literal_String 11545 11546 11547@geindex Named numbers 11548@geindex representation of 11549 11550@geindex Universal_Literal_String 11551 11552The prefix of @code{Universal_Literal_String} must be a named 11553number. The static result is the string consisting of the characters of 11554the number as defined in the original source. This allows the user 11555program to access the actual text of named numbers without intermediate 11556conversions and without the need to enclose the strings in quotes (which 11557would preclude their use as numbers). 11558 11559For example, the following program prints the first 50 digits of pi: 11560 11561@example 11562with Text_IO; use Text_IO; 11563with Ada.Numerics; 11564procedure Pi is 11565begin 11566 Put (Ada.Numerics.Pi'Universal_Literal_String); 11567end; 11568@end example 11569 11570@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 11571@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1a9} 11572@section Attribute Unrestricted_Access 11573 11574 11575@geindex Access 11576@geindex unrestricted 11577 11578@geindex Unrestricted_Access 11579 11580The @code{Unrestricted_Access} attribute is similar to @code{Access} 11581except that all accessibility and aliased view checks are omitted. This 11582is a user-beware attribute. 11583 11584For objects, it is similar to @code{Address}, for which it is a 11585desirable replacement where the value desired is an access type. 11586In other words, its effect is similar to first applying the 11587@code{Address} attribute and then doing an unchecked conversion to a 11588desired access type. 11589 11590For subprograms, @code{P'Unrestricted_Access} may be used where 11591@code{P'Access} would be illegal, to construct a value of a 11592less-nested named access type that designates a more-nested 11593subprogram. This value may be used in indirect calls, so long as the 11594more-nested subprogram still exists; once the subprogram containing it 11595has returned, such calls are erroneous. For example: 11596 11597@example 11598package body P is 11599 11600 type Less_Nested is not null access procedure; 11601 Global : Less_Nested; 11602 11603 procedure P1 is 11604 begin 11605 Global.all; 11606 end P1; 11607 11608 procedure P2 is 11609 Local_Var : Integer; 11610 11611 procedure More_Nested is 11612 begin 11613 ... Local_Var ... 11614 end More_Nested; 11615 begin 11616 Global := More_Nested'Unrestricted_Access; 11617 P1; 11618 end P2; 11619 11620end P; 11621@end example 11622 11623When P1 is called from P2, the call via Global is OK, but if P1 were 11624called after P2 returns, it would be an erroneous use of a dangling 11625pointer. 11626 11627For objects, it is possible to use @code{Unrestricted_Access} for any 11628type. However, if the result is of an access-to-unconstrained array 11629subtype, then the resulting pointer has the same scope as the context 11630of the attribute, and must not be returned to some enclosing scope. 11631For instance, if a function uses @code{Unrestricted_Access} to create 11632an access-to-unconstrained-array and returns that value to the caller, 11633the result will involve dangling pointers. In addition, it is only 11634valid to create pointers to unconstrained arrays using this attribute 11635if the pointer has the normal default 'fat' representation where a 11636pointer has two components, one points to the array and one points to 11637the bounds. If a size clause is used to force 'thin' representation 11638for a pointer to unconstrained where there is only space for a single 11639pointer, then the resulting pointer is not usable. 11640 11641In the simple case where a direct use of Unrestricted_Access attempts 11642to make a thin pointer for a non-aliased object, the compiler will 11643reject the use as illegal, as shown in the following example: 11644 11645@example 11646with System; use System; 11647procedure SliceUA2 is 11648 type A is access all String; 11649 for A'Size use Standard'Address_Size; 11650 11651 procedure P (Arg : A) is 11652 begin 11653 null; 11654 end P; 11655 11656 X : String := "hello world!"; 11657 X2 : aliased String := "hello world!"; 11658 11659 AV : A := X'Unrestricted_Access; -- ERROR 11660 | 11661>>> illegal use of Unrestricted_Access attribute 11662>>> attempt to generate thin pointer to unaliased object 11663 11664begin 11665 P (X'Unrestricted_Access); -- ERROR 11666 | 11667>>> illegal use of Unrestricted_Access attribute 11668>>> attempt to generate thin pointer to unaliased object 11669 11670 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11671 | 11672>>> illegal use of Unrestricted_Access attribute 11673>>> attempt to generate thin pointer to unaliased object 11674 11675 P (X2'Unrestricted_Access); -- OK 11676end; 11677@end example 11678 11679but other cases cannot be detected by the compiler, and are 11680considered to be erroneous. Consider the following example: 11681 11682@example 11683with System; use System; 11684with System; use System; 11685procedure SliceUA is 11686 type AF is access all String; 11687 11688 type A is access all String; 11689 for A'Size use Standard'Address_Size; 11690 11691 procedure P (Arg : A) is 11692 begin 11693 if Arg'Length /= 6 then 11694 raise Program_Error; 11695 end if; 11696 end P; 11697 11698 X : String := "hello world!"; 11699 Y : AF := X (7 .. 12)'Unrestricted_Access; 11700 11701begin 11702 P (A (Y)); 11703end; 11704@end example 11705 11706A normal unconstrained array value 11707or a constrained array object marked as aliased has the bounds in memory 11708just before the array, so a thin pointer can retrieve both the data and 11709the bounds. But in this case, the non-aliased object @code{X} does not have the 11710bounds before the string. If the size clause for type @code{A} 11711were not present, then the pointer 11712would be a fat pointer, where one component is a pointer to the bounds, 11713and all would be well. But with the size clause present, the conversion from 11714fat pointer to thin pointer in the call loses the bounds, and so this 11715is erroneous, and the program likely raises a @code{Program_Error} exception. 11716 11717In general, it is advisable to completely 11718avoid mixing the use of thin pointers and the use of 11719@code{Unrestricted_Access} where the designated type is an 11720unconstrained array. The use of thin pointers should be restricted to 11721cases of porting legacy code that implicitly assumes the size of pointers, 11722and such code should not in any case be using this attribute. 11723 11724Another erroneous situation arises if the attribute is 11725applied to a constant. The resulting pointer can be used to access the 11726constant, but the effect of trying to modify a constant in this manner 11727is not well-defined. Consider this example: 11728 11729@example 11730P : constant Integer := 4; 11731type R is access all Integer; 11732RV : R := P'Unrestricted_Access; 11733.. 11734RV.all := 3; 11735@end example 11736 11737Here we attempt to modify the constant P from 4 to 3, but the compiler may 11738or may not notice this attempt, and subsequent references to P may yield 11739either the value 3 or the value 4 or the assignment may blow up if the 11740compiler decides to put P in read-only memory. One particular case where 11741@code{Unrestricted_Access} can be used in this way is to modify the 11742value of an @code{in} parameter: 11743 11744@example 11745procedure K (S : in String) is 11746 type R is access all Character; 11747 RV : R := S (3)'Unrestricted_Access; 11748begin 11749 RV.all := 'a'; 11750end; 11751@end example 11752 11753In general this is a risky approach. It may appear to "work" but such uses of 11754@code{Unrestricted_Access} are potentially non-portable, even from one version 11755of GNAT to another, so are best avoided if possible. 11756 11757@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes 11758@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1aa} 11759@section Attribute Update 11760 11761 11762@geindex Update 11763 11764The @code{Update} attribute creates a copy of an array or record value 11765with one or more modified components. The syntax is: 11766 11767@example 11768PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 11769PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 11770PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 11771 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 11772 11773MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 11774INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 11775INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 11776@end example 11777 11778where @code{PREFIX} is the name of an array or record object, the 11779association list in parentheses does not contain an @code{others} 11780choice and the box symbol @code{<>} may not appear in any 11781expression. The effect is to yield a copy of the array or record value 11782which is unchanged apart from the components mentioned in the 11783association list, which are changed to the indicated value. The 11784original value of the array or record value is not affected. For 11785example: 11786 11787@example 11788type Arr is Array (1 .. 5) of Integer; 11789... 11790Avar1 : Arr := (1,2,3,4,5); 11791Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 11792@end example 11793 11794yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 11795begin unmodified. Similarly: 11796 11797@example 11798type Rec is A, B, C : Integer; 11799... 11800Rvar1 : Rec := (A => 1, B => 2, C => 3); 11801Rvar2 : Rec := Rvar1'Update (B => 20); 11802@end example 11803 11804yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 11805with @code{Rvar1} being unmodifed. 11806Note that the value of the attribute reference is computed 11807completely before it is used. This means that if you write: 11808 11809@example 11810Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 11811@end example 11812 11813then the value of @code{Avar1} is not modified if @code{Function_Call} 11814raises an exception, unlike the effect of a series of direct assignments 11815to elements of @code{Avar1}. In general this requires that 11816two extra complete copies of the object are required, which should be 11817kept in mind when considering efficiency. 11818 11819The @code{Update} attribute cannot be applied to prefixes of a limited 11820type, and cannot reference discriminants in the case of a record type. 11821The accessibility level of an Update attribute result object is defined 11822as for an aggregate. 11823 11824In the record case, no component can be mentioned more than once. In 11825the array case, two overlapping ranges can appear in the association list, 11826in which case the modifications are processed left to right. 11827 11828Multi-dimensional arrays can be modified, as shown by this example: 11829 11830@example 11831A : array (1 .. 10, 1 .. 10) of Integer; 11832.. 11833A := A'Update ((1, 2) => 20, (3, 4) => 30); 11834@end example 11835 11836which changes element (1,2) to 20 and (3,4) to 30. 11837 11838@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes 11839@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1ab} 11840@section Attribute Valid_Scalars 11841 11842 11843@geindex Valid_Scalars 11844 11845The @code{'Valid_Scalars} attribute is intended to make it easier to check the 11846validity of scalar subcomponents of composite objects. The attribute is defined 11847for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type 11848except for tagged private or @code{Unchecked_Union} types. The value of the 11849attribute is of type @code{Boolean}. 11850 11851@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of 11852@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if 11853@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent 11854to attribute @code{'Valid} for scalar types. 11855 11856It is not specified in what order the subcomponents are checked, nor whether 11857any more are checked after any one of them is determined to be invalid. If the 11858prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated 11859specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then 11860only the subcomponents of @code{T} are checked; in other words, components of 11861extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. 11862 11863The compiler will issue a warning if it can be determined at compile time that 11864the prefix of the attribute has no scalar subcomponents. 11865 11866Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of 11867a large variant record. If the attribute is called in many places in the same 11868program applied to objects of the same type, it can reduce program size to 11869write a function with a single use of the attribute, and then call that 11870function from multiple places. 11871 11872@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 11873@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1ac} 11874@section Attribute VADS_Size 11875 11876 11877@geindex Size 11878@geindex VADS compatibility 11879 11880@geindex VADS_Size 11881 11882The @code{'VADS_Size} attribute is intended to make it easier to port 11883legacy code which relies on the semantics of @code{'Size} as implemented 11884by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 11885same semantic interpretation. In particular, @code{'VADS_Size} applied 11886to a predefined or other primitive type with no Size clause yields the 11887Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 11888typical machines). In addition @code{'VADS_Size} applied to an object 11889gives the result that would be obtained by applying the attribute to 11890the corresponding type. 11891 11892@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 11893@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1ad}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15f} 11894@section Attribute Value_Size 11895 11896 11897@geindex Size 11898@geindex setting for not-first subtype 11899 11900@geindex Value_Size 11901 11902@code{type'Value_Size} is the number of bits required to represent 11903a value of the given subtype. It is the same as @code{type'Size}, 11904but, unlike @code{Size}, may be set for non-first subtypes. 11905 11906@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 11907@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1ae} 11908@section Attribute Wchar_T_Size 11909 11910 11911@geindex Wchar_T_Size 11912 11913@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 11914prefix) provides the size in bits of the C @code{wchar_t} type 11915primarily for constructing the definition of this type in 11916package @code{Interfaces.C}. The result is a static constant. 11917 11918@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 11919@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1af} 11920@section Attribute Word_Size 11921 11922 11923@geindex Word_Size 11924 11925@code{Standard'Word_Size} (@code{Standard} is the only permissible 11926prefix) provides the value @code{System.Word_Size}. The result is 11927a static constant. 11928 11929@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 11930@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b0}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b1} 11931@chapter Standard and Implementation Defined Restrictions 11932 11933 11934All Ada Reference Manual-defined Restriction identifiers are implemented: 11935 11936 11937@itemize * 11938 11939@item 11940language-defined restrictions (see 13.12.1) 11941 11942@item 11943tasking restrictions (see D.7) 11944 11945@item 11946high integrity restrictions (see H.4) 11947@end itemize 11948 11949GNAT implements additional restriction identifiers. All restrictions, whether 11950language defined or GNAT-specific, are listed in the following. 11951 11952@menu 11953* Partition-Wide Restrictions:: 11954* Program Unit Level Restrictions:: 11955 11956@end menu 11957 11958@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 11959@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b2}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b3} 11960@section Partition-Wide Restrictions 11961 11962 11963There are two separate lists of restriction identifiers. The first 11964set requires consistency throughout a partition (in other words, if the 11965restriction identifier is used for any compilation unit in the partition, 11966then all compilation units in the partition must obey the restriction). 11967 11968@menu 11969* Immediate_Reclamation:: 11970* Max_Asynchronous_Select_Nesting:: 11971* Max_Entry_Queue_Length:: 11972* Max_Protected_Entries:: 11973* Max_Select_Alternatives:: 11974* Max_Storage_At_Blocking:: 11975* Max_Task_Entries:: 11976* Max_Tasks:: 11977* No_Abort_Statements:: 11978* No_Access_Parameter_Allocators:: 11979* No_Access_Subprograms:: 11980* No_Allocators:: 11981* No_Anonymous_Allocators:: 11982* No_Asynchronous_Control:: 11983* No_Calendar:: 11984* No_Coextensions:: 11985* No_Default_Initialization:: 11986* No_Delay:: 11987* No_Dependence:: 11988* No_Direct_Boolean_Operators:: 11989* No_Dispatch:: 11990* No_Dispatching_Calls:: 11991* No_Dynamic_Attachment:: 11992* No_Dynamic_Priorities:: 11993* No_Entry_Calls_In_Elaboration_Code:: 11994* No_Enumeration_Maps:: 11995* No_Exception_Handlers:: 11996* No_Exception_Propagation:: 11997* No_Exception_Registration:: 11998* No_Exceptions:: 11999* No_Finalization:: 12000* No_Fixed_Point:: 12001* No_Floating_Point:: 12002* No_Implicit_Conditionals:: 12003* No_Implicit_Dynamic_Code:: 12004* No_Implicit_Heap_Allocations:: 12005* No_Implicit_Protected_Object_Allocations:: 12006* No_Implicit_Task_Allocations:: 12007* No_Initialize_Scalars:: 12008* No_IO:: 12009* No_Local_Allocators:: 12010* No_Local_Protected_Objects:: 12011* No_Local_Timing_Events:: 12012* No_Long_Long_Integers:: 12013* No_Multiple_Elaboration:: 12014* No_Nested_Finalization:: 12015* No_Protected_Type_Allocators:: 12016* No_Protected_Types:: 12017* No_Recursion:: 12018* No_Reentrancy:: 12019* No_Relative_Delay:: 12020* No_Requeue_Statements:: 12021* No_Secondary_Stack:: 12022* No_Select_Statements:: 12023* No_Specific_Termination_Handlers:: 12024* No_Specification_of_Aspect:: 12025* No_Standard_Allocators_After_Elaboration:: 12026* No_Standard_Storage_Pools:: 12027* No_Stream_Optimizations:: 12028* No_Streams:: 12029* No_Task_Allocators:: 12030* No_Task_At_Interrupt_Priority:: 12031* No_Task_Attributes_Package:: 12032* No_Task_Hierarchy:: 12033* No_Task_Termination:: 12034* No_Tasking:: 12035* No_Terminate_Alternatives:: 12036* No_Unchecked_Access:: 12037* No_Unchecked_Conversion:: 12038* No_Unchecked_Deallocation:: 12039* No_Use_Of_Entity:: 12040* Pure_Barriers:: 12041* Simple_Barriers:: 12042* Static_Priorities:: 12043* Static_Storage_Size:: 12044 12045@end menu 12046 12047@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 12048@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b4} 12049@subsection Immediate_Reclamation 12050 12051 12052@geindex Immediate_Reclamation 12053 12054[RM H.4] This restriction ensures that, except for storage occupied by 12055objects created by allocators and not deallocated via unchecked 12056deallocation, any storage reserved at run time for an object is 12057immediately reclaimed when the object no longer exists. 12058 12059@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 12060@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b5} 12061@subsection Max_Asynchronous_Select_Nesting 12062 12063 12064@geindex Max_Asynchronous_Select_Nesting 12065 12066[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 12067selects. Violations of this restriction with a value of zero are 12068detected at compile time. Violations of this restriction with values 12069other than zero cause Storage_Error to be raised. 12070 12071@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 12072@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1b6} 12073@subsection Max_Entry_Queue_Length 12074 12075 12076@geindex Max_Entry_Queue_Length 12077 12078[RM D.7] This restriction is a declaration that any protected entry compiled in 12079the scope of the restriction has at most the specified number of 12080tasks waiting on the entry at any one time, and so no queue is required. 12081Note that this restriction is checked at run time. Violation of this 12082restriction results in the raising of Program_Error exception at the point of 12083the call. 12084 12085@geindex Max_Entry_Queue_Depth 12086 12087The restriction @code{Max_Entry_Queue_Depth} is recognized as a 12088synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 12089compatibility purposes (and a warning will be generated for its use if 12090warnings on obsolescent features are activated). 12091 12092@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 12093@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1b7} 12094@subsection Max_Protected_Entries 12095 12096 12097@geindex Max_Protected_Entries 12098 12099[RM D.7] Specifies the maximum number of entries per protected type. The 12100bounds of every entry family of a protected unit shall be static, or shall be 12101defined by a discriminant of a subtype whose corresponding bound is static. 12102 12103@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 12104@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1b8} 12105@subsection Max_Select_Alternatives 12106 12107 12108@geindex Max_Select_Alternatives 12109 12110[RM D.7] Specifies the maximum number of alternatives in a selective accept. 12111 12112@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 12113@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1b9} 12114@subsection Max_Storage_At_Blocking 12115 12116 12117@geindex Max_Storage_At_Blocking 12118 12119[RM D.7] Specifies the maximum portion (in storage elements) of a task's 12120Storage_Size that can be retained by a blocked task. A violation of this 12121restriction causes Storage_Error to be raised. 12122 12123@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 12124@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1ba} 12125@subsection Max_Task_Entries 12126 12127 12128@geindex Max_Task_Entries 12129 12130[RM D.7] Specifies the maximum number of entries 12131per task. The bounds of every entry family 12132of a task unit shall be static, or shall be 12133defined by a discriminant of a subtype whose 12134corresponding bound is static. 12135 12136@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 12137@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1bb} 12138@subsection Max_Tasks 12139 12140 12141@geindex Max_Tasks 12142 12143[RM D.7] Specifies the maximum number of task that may be created, not 12144counting the creation of the environment task. Violations of this 12145restriction with a value of zero are detected at compile 12146time. Violations of this restriction with values other than zero cause 12147Storage_Error to be raised. 12148 12149@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 12150@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1bc} 12151@subsection No_Abort_Statements 12152 12153 12154@geindex No_Abort_Statements 12155 12156[RM D.7] There are no abort_statements, and there are 12157no calls to Task_Identification.Abort_Task. 12158 12159@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 12160@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1bd} 12161@subsection No_Access_Parameter_Allocators 12162 12163 12164@geindex No_Access_Parameter_Allocators 12165 12166[RM H.4] This restriction ensures at compile time that there are no 12167occurrences of an allocator as the actual parameter to an access 12168parameter. 12169 12170@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 12171@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1be} 12172@subsection No_Access_Subprograms 12173 12174 12175@geindex No_Access_Subprograms 12176 12177[RM H.4] This restriction ensures at compile time that there are no 12178declarations of access-to-subprogram types. 12179 12180@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 12181@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1bf} 12182@subsection No_Allocators 12183 12184 12185@geindex No_Allocators 12186 12187[RM H.4] This restriction ensures at compile time that there are no 12188occurrences of an allocator. 12189 12190@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 12191@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c0} 12192@subsection No_Anonymous_Allocators 12193 12194 12195@geindex No_Anonymous_Allocators 12196 12197[RM H.4] This restriction ensures at compile time that there are no 12198occurrences of an allocator of anonymous access type. 12199 12200@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 12201@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c1} 12202@subsection No_Asynchronous_Control 12203 12204 12205@geindex No_Asynchronous_Control 12206 12207[RM J.13] This restriction ensures at compile time that there are no semantic 12208dependences on the predefined package Asynchronous_Task_Control. 12209 12210@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 12211@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c2} 12212@subsection No_Calendar 12213 12214 12215@geindex No_Calendar 12216 12217[GNAT] This restriction ensures at compile time that there are no semantic 12218dependences on package Calendar. 12219 12220@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 12221@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c3} 12222@subsection No_Coextensions 12223 12224 12225@geindex No_Coextensions 12226 12227[RM H.4] This restriction ensures at compile time that there are no 12228coextensions. See 3.10.2. 12229 12230@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 12231@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c4} 12232@subsection No_Default_Initialization 12233 12234 12235@geindex No_Default_Initialization 12236 12237[GNAT] This restriction prohibits any instance of default initialization 12238of variables. The binder implements a consistency rule which prevents 12239any unit compiled without the restriction from with'ing a unit with the 12240restriction (this allows the generation of initialization procedures to 12241be skipped, since you can be sure that no call is ever generated to an 12242initialization procedure in a unit with the restriction active). If used 12243in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 12244is to prohibit all cases of variables declared without a specific 12245initializer (including the case of OUT scalar parameters). 12246 12247@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 12248@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c5} 12249@subsection No_Delay 12250 12251 12252@geindex No_Delay 12253 12254[RM H.4] This restriction ensures at compile time that there are no 12255delay statements and no semantic dependences on package Calendar. 12256 12257@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 12258@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1c6} 12259@subsection No_Dependence 12260 12261 12262@geindex No_Dependence 12263 12264[RM 13.12.1] This restriction ensures at compile time that there are no 12265dependences on a library unit. 12266 12267@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 12268@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1c7} 12269@subsection No_Direct_Boolean_Operators 12270 12271 12272@geindex No_Direct_Boolean_Operators 12273 12274[GNAT] This restriction ensures that no logical operators (and/or/xor) 12275are used on operands of type Boolean (or any type derived from Boolean). 12276This is intended for use in safety critical programs where the certification 12277protocol requires the use of short-circuit (and then, or else) forms for all 12278composite boolean operations. 12279 12280@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 12281@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1c8} 12282@subsection No_Dispatch 12283 12284 12285@geindex No_Dispatch 12286 12287[RM H.4] This restriction ensures at compile time that there are no 12288occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 12289 12290@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 12291@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1c9} 12292@subsection No_Dispatching_Calls 12293 12294 12295@geindex No_Dispatching_Calls 12296 12297[GNAT] This restriction ensures at compile time that the code generated by the 12298compiler involves no dispatching calls. The use of this restriction allows the 12299safe use of record extensions, classwide membership tests and other classwide 12300features not involving implicit dispatching. This restriction ensures that 12301the code contains no indirect calls through a dispatching mechanism. Note that 12302this includes internally-generated calls created by the compiler, for example 12303in the implementation of class-wide objects assignments. The 12304membership test is allowed in the presence of this restriction, because its 12305implementation requires no dispatching. 12306This restriction is comparable to the official Ada restriction 12307@code{No_Dispatch} except that it is a bit less restrictive in that it allows 12308all classwide constructs that do not imply dispatching. 12309The following example indicates constructs that violate this restriction. 12310 12311@example 12312package Pkg is 12313 type T is tagged record 12314 Data : Natural; 12315 end record; 12316 procedure P (X : T); 12317 12318 type DT is new T with record 12319 More_Data : Natural; 12320 end record; 12321 procedure Q (X : DT); 12322end Pkg; 12323 12324with Pkg; use Pkg; 12325procedure Example is 12326 procedure Test (O : T'Class) is 12327 N : Natural := O'Size;-- Error: Dispatching call 12328 C : T'Class := O; -- Error: implicit Dispatching Call 12329 begin 12330 if O in DT'Class then -- OK : Membership test 12331 Q (DT (O)); -- OK : Type conversion plus direct call 12332 else 12333 P (O); -- Error: Dispatching call 12334 end if; 12335 end Test; 12336 12337 Obj : DT; 12338begin 12339 P (Obj); -- OK : Direct call 12340 P (T (Obj)); -- OK : Type conversion plus direct call 12341 P (T'Class (Obj)); -- Error: Dispatching call 12342 12343 Test (Obj); -- OK : Type conversion 12344 12345 if Obj in T'Class then -- OK : Membership test 12346 null; 12347 end if; 12348end Example; 12349@end example 12350 12351@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 12352@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1ca} 12353@subsection No_Dynamic_Attachment 12354 12355 12356@geindex No_Dynamic_Attachment 12357 12358[RM D.7] This restriction ensures that there is no call to any of the 12359operations defined in package Ada.Interrupts 12360(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 12361Detach_Handler, and Reference). 12362 12363@geindex No_Dynamic_Interrupts 12364 12365The restriction @code{No_Dynamic_Interrupts} is recognized as a 12366synonym for @code{No_Dynamic_Attachment}. This is retained for historical 12367compatibility purposes (and a warning will be generated for its use if 12368warnings on obsolescent features are activated). 12369 12370@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 12371@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1cb} 12372@subsection No_Dynamic_Priorities 12373 12374 12375@geindex No_Dynamic_Priorities 12376 12377[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 12378 12379@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 12380@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1cc} 12381@subsection No_Entry_Calls_In_Elaboration_Code 12382 12383 12384@geindex No_Entry_Calls_In_Elaboration_Code 12385 12386[GNAT] This restriction ensures at compile time that no task or protected entry 12387calls are made during elaboration code. As a result of the use of this 12388restriction, the compiler can assume that no code past an accept statement 12389in a task can be executed at elaboration time. 12390 12391@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 12392@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1cd} 12393@subsection No_Enumeration_Maps 12394 12395 12396@geindex No_Enumeration_Maps 12397 12398[GNAT] This restriction ensures at compile time that no operations requiring 12399enumeration maps are used (that is Image and Value attributes applied 12400to enumeration types). 12401 12402@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 12403@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1ce} 12404@subsection No_Exception_Handlers 12405 12406 12407@geindex No_Exception_Handlers 12408 12409[GNAT] This restriction ensures at compile time that there are no explicit 12410exception handlers. It also indicates that no exception propagation will 12411be provided. In this mode, exceptions may be raised but will result in 12412an immediate call to the last chance handler, a routine that the user 12413must define with the following profile: 12414 12415@example 12416procedure Last_Chance_Handler 12417 (Source_Location : System.Address; Line : Integer); 12418pragma Export (C, Last_Chance_Handler, 12419 "__gnat_last_chance_handler"); 12420@end example 12421 12422The parameter is a C null-terminated string representing a message to be 12423associated with the exception (typically the source location of the raise 12424statement generated by the compiler). The Line parameter when nonzero 12425represents the line number in the source program where the raise occurs. 12426 12427@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 12428@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1cf} 12429@subsection No_Exception_Propagation 12430 12431 12432@geindex No_Exception_Propagation 12433 12434[GNAT] This restriction guarantees that exceptions are never propagated 12435to an outer subprogram scope. The only case in which an exception may 12436be raised is when the handler is statically in the same subprogram, so 12437that the effect of a raise is essentially like a goto statement. Any 12438other raise statement (implicit or explicit) will be considered 12439unhandled. Exception handlers are allowed, but may not contain an 12440exception occurrence identifier (exception choice). In addition, use of 12441the package GNAT.Current_Exception is not permitted, and reraise 12442statements (raise with no operand) are not permitted. 12443 12444@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 12445@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d0} 12446@subsection No_Exception_Registration 12447 12448 12449@geindex No_Exception_Registration 12450 12451[GNAT] This restriction ensures at compile time that no stream operations for 12452types Exception_Id or Exception_Occurrence are used. This also makes it 12453impossible to pass exceptions to or from a partition with this restriction 12454in a distributed environment. If this restriction is active, the generated 12455code is simplified by omitting the otherwise-required global registration 12456of exceptions when they are declared. 12457 12458@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 12459@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d1} 12460@subsection No_Exceptions 12461 12462 12463@geindex No_Exceptions 12464 12465[RM H.4] This restriction ensures at compile time that there are no 12466raise statements and no exception handlers. 12467 12468@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 12469@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d2} 12470@subsection No_Finalization 12471 12472 12473@geindex No_Finalization 12474 12475[GNAT] This restriction disables the language features described in 12476chapter 7.6 of the Ada 2005 RM as well as all form of code generation 12477performed by the compiler to support these features. The following types 12478are no longer considered controlled when this restriction is in effect: 12479 12480 12481@itemize * 12482 12483@item 12484@code{Ada.Finalization.Controlled} 12485 12486@item 12487@code{Ada.Finalization.Limited_Controlled} 12488 12489@item 12490Derivations from @code{Controlled} or @code{Limited_Controlled} 12491 12492@item 12493Class-wide types 12494 12495@item 12496Protected types 12497 12498@item 12499Task types 12500 12501@item 12502Array and record types with controlled components 12503@end itemize 12504 12505The compiler no longer generates code to initialize, finalize or adjust an 12506object or a nested component, either declared on the stack or on the heap. The 12507deallocation of a controlled object no longer finalizes its contents. 12508 12509@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 12510@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d3} 12511@subsection No_Fixed_Point 12512 12513 12514@geindex No_Fixed_Point 12515 12516[RM H.4] This restriction ensures at compile time that there are no 12517occurrences of fixed point types and operations. 12518 12519@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 12520@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d4} 12521@subsection No_Floating_Point 12522 12523 12524@geindex No_Floating_Point 12525 12526[RM H.4] This restriction ensures at compile time that there are no 12527occurrences of floating point types and operations. 12528 12529@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 12530@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d5} 12531@subsection No_Implicit_Conditionals 12532 12533 12534@geindex No_Implicit_Conditionals 12535 12536[GNAT] This restriction ensures that the generated code does not contain any 12537implicit conditionals, either by modifying the generated code where possible, 12538or by rejecting any construct that would otherwise generate an implicit 12539conditional. Note that this check does not include run time constraint 12540checks, which on some targets may generate implicit conditionals as 12541well. To control the latter, constraint checks can be suppressed in the 12542normal manner. Constructs generating implicit conditionals include comparisons 12543of composite objects and the Max/Min attributes. 12544 12545@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 12546@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1d6} 12547@subsection No_Implicit_Dynamic_Code 12548 12549 12550@geindex No_Implicit_Dynamic_Code 12551 12552@geindex trampoline 12553 12554[GNAT] This restriction prevents the compiler from building 'trampolines'. 12555This is a structure that is built on the stack and contains dynamic 12556code to be executed at run time. On some targets, a trampoline is 12557built for the following features: @code{Access}, 12558@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 12559nested task bodies; primitive operations of nested tagged types. 12560Trampolines do not work on machines that prevent execution of stack 12561data. For example, on windows systems, enabling DEP (data execution 12562protection) will cause trampolines to raise an exception. 12563Trampolines are also quite slow at run time. 12564 12565On many targets, trampolines have been largely eliminated. Look at the 12566version of system.ads for your target --- if it has 12567Always_Compatible_Rep equal to False, then trampolines are largely 12568eliminated. In particular, a trampoline is built for the following 12569features: @code{Address} of a nested subprogram; 12570@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 12571but only if pragma Favor_Top_Level applies, or the access type has a 12572foreign-language convention; primitive operations of nested tagged 12573types. 12574 12575@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 12576@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1d7} 12577@subsection No_Implicit_Heap_Allocations 12578 12579 12580@geindex No_Implicit_Heap_Allocations 12581 12582[RM D.7] No constructs are allowed to cause implicit heap allocation. 12583 12584@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12585@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1d8} 12586@subsection No_Implicit_Protected_Object_Allocations 12587 12588 12589@geindex No_Implicit_Protected_Object_Allocations 12590 12591[GNAT] No constructs are allowed to cause implicit heap allocation of a 12592protected object. 12593 12594@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12595@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1d9} 12596@subsection No_Implicit_Task_Allocations 12597 12598 12599@geindex No_Implicit_Task_Allocations 12600 12601[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12602 12603@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12604@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1da} 12605@subsection No_Initialize_Scalars 12606 12607 12608@geindex No_Initialize_Scalars 12609 12610[GNAT] This restriction ensures that no unit in the partition is compiled with 12611pragma Initialize_Scalars. This allows the generation of more efficient 12612code, and in particular eliminates dummy null initialization routines that 12613are otherwise generated for some record and array types. 12614 12615@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12616@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1db} 12617@subsection No_IO 12618 12619 12620@geindex No_IO 12621 12622[RM H.4] This restriction ensures at compile time that there are no 12623dependences on any of the library units Sequential_IO, Direct_IO, 12624Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12625 12626@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12627@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1dc} 12628@subsection No_Local_Allocators 12629 12630 12631@geindex No_Local_Allocators 12632 12633[RM H.4] This restriction ensures at compile time that there are no 12634occurrences of an allocator in subprograms, generic subprograms, tasks, 12635and entry bodies. 12636 12637@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12638@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1dd} 12639@subsection No_Local_Protected_Objects 12640 12641 12642@geindex No_Local_Protected_Objects 12643 12644[RM D.7] This restriction ensures at compile time that protected objects are 12645only declared at the library level. 12646 12647@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12648@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1de} 12649@subsection No_Local_Timing_Events 12650 12651 12652@geindex No_Local_Timing_Events 12653 12654[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 12655declared at the library level. 12656 12657@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12658@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1df} 12659@subsection No_Long_Long_Integers 12660 12661 12662@geindex No_Long_Long_Integers 12663 12664[GNAT] This partition-wide restriction forbids any explicit reference to 12665type Standard.Long_Long_Integer, and also forbids declaring range types whose 12666implicit base type is Long_Long_Integer, and modular types whose size exceeds 12667Long_Integer'Size. 12668 12669@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12670@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e0} 12671@subsection No_Multiple_Elaboration 12672 12673 12674@geindex No_Multiple_Elaboration 12675 12676[GNAT] When this restriction is active, we are not requesting control-flow 12677preservation with -fpreserve-control-flow, and the static elaboration model is 12678used, the compiler is allowed to suppress the elaboration counter normally 12679associated with the unit, even if the unit has elaboration code. This counter 12680is typically used to check for access before elaboration and to control 12681multiple elaboration attempts. If the restriction is used, then the 12682situations in which multiple elaboration is possible, including non-Ada main 12683programs and Stand Alone libraries, are not permitted and will be diagnosed 12684by the binder. 12685 12686@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12687@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e1} 12688@subsection No_Nested_Finalization 12689 12690 12691@geindex No_Nested_Finalization 12692 12693[RM D.7] All objects requiring finalization are declared at the library level. 12694 12695@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12696@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e2} 12697@subsection No_Protected_Type_Allocators 12698 12699 12700@geindex No_Protected_Type_Allocators 12701 12702[RM D.7] This restriction ensures at compile time that there are no allocator 12703expressions that attempt to allocate protected objects. 12704 12705@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 12706@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e3} 12707@subsection No_Protected_Types 12708 12709 12710@geindex No_Protected_Types 12711 12712[RM H.4] This restriction ensures at compile time that there are no 12713declarations of protected types or protected objects. 12714 12715@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 12716@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e4} 12717@subsection No_Recursion 12718 12719 12720@geindex No_Recursion 12721 12722[RM H.4] A program execution is erroneous if a subprogram is invoked as 12723part of its execution. 12724 12725@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 12726@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e5} 12727@subsection No_Reentrancy 12728 12729 12730@geindex No_Reentrancy 12731 12732[RM H.4] A program execution is erroneous if a subprogram is executed by 12733two tasks at the same time. 12734 12735@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 12736@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1e6} 12737@subsection No_Relative_Delay 12738 12739 12740@geindex No_Relative_Delay 12741 12742[RM D.7] This restriction ensures at compile time that there are no delay 12743relative statements and prevents expressions such as @code{delay 1.23;} from 12744appearing in source code. 12745 12746@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 12747@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1e7} 12748@subsection No_Requeue_Statements 12749 12750 12751@geindex No_Requeue_Statements 12752 12753[RM D.7] This restriction ensures at compile time that no requeue statements 12754are permitted and prevents keyword @code{requeue} from being used in source 12755code. 12756 12757@geindex No_Requeue 12758 12759The restriction @code{No_Requeue} is recognized as a 12760synonym for @code{No_Requeue_Statements}. This is retained for historical 12761compatibility purposes (and a warning will be generated for its use if 12762warnings on oNobsolescent features are activated). 12763 12764@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 12765@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1e8} 12766@subsection No_Secondary_Stack 12767 12768 12769@geindex No_Secondary_Stack 12770 12771[GNAT] This restriction ensures at compile time that the generated code 12772does not contain any reference to the secondary stack. The secondary 12773stack is used to implement functions returning unconstrained objects 12774(arrays or records) on some targets. Suppresses the allocation of 12775secondary stacks for tasks (excluding the environment task) at run time. 12776 12777@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 12778@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1e9} 12779@subsection No_Select_Statements 12780 12781 12782@geindex No_Select_Statements 12783 12784[RM D.7] This restriction ensures at compile time no select statements of any 12785kind are permitted, that is the keyword @code{select} may not appear. 12786 12787@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 12788@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ea} 12789@subsection No_Specific_Termination_Handlers 12790 12791 12792@geindex No_Specific_Termination_Handlers 12793 12794[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 12795or to Ada.Task_Termination.Specific_Handler. 12796 12797@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 12798@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1eb} 12799@subsection No_Specification_of_Aspect 12800 12801 12802@geindex No_Specification_of_Aspect 12803 12804[RM 13.12.1] This restriction checks at compile time that no aspect 12805specification, attribute definition clause, or pragma is given for a 12806given aspect. 12807 12808@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 12809@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1ec} 12810@subsection No_Standard_Allocators_After_Elaboration 12811 12812 12813@geindex No_Standard_Allocators_After_Elaboration 12814 12815[RM D.7] Specifies that an allocator using a standard storage pool 12816should never be evaluated at run time after the elaboration of the 12817library items of the partition has completed. Otherwise, Storage_Error 12818is raised. 12819 12820@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 12821@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1ed} 12822@subsection No_Standard_Storage_Pools 12823 12824 12825@geindex No_Standard_Storage_Pools 12826 12827[GNAT] This restriction ensures at compile time that no access types 12828use the standard default storage pool. Any access type declared must 12829have an explicit Storage_Pool attribute defined specifying a 12830user-defined storage pool. 12831 12832@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 12833@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1ee} 12834@subsection No_Stream_Optimizations 12835 12836 12837@geindex No_Stream_Optimizations 12838 12839[GNAT] This restriction affects the performance of stream operations on types 12840@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 12841compiler uses block reads and writes when manipulating @code{String} objects 12842due to their supperior performance. When this restriction is in effect, the 12843compiler performs all IO operations on a per-character basis. 12844 12845@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 12846@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1ef} 12847@subsection No_Streams 12848 12849 12850@geindex No_Streams 12851 12852[GNAT] This restriction ensures at compile/bind time that there are no 12853stream objects created and no use of stream attributes. 12854This restriction does not forbid dependences on the package 12855@code{Ada.Streams}. So it is permissible to with 12856@code{Ada.Streams} (or another package that does so itself) 12857as long as no actual stream objects are created and no 12858stream attributes are used. 12859 12860Note that the use of restriction allows optimization of tagged types, 12861since they do not need to worry about dispatching stream operations. 12862To take maximum advantage of this space-saving optimization, any 12863unit declaring a tagged type should be compiled with the restriction, 12864though this is not required. 12865 12866@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 12867@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f0} 12868@subsection No_Task_Allocators 12869 12870 12871@geindex No_Task_Allocators 12872 12873[RM D.7] There are no allocators for task types 12874or types containing task subcomponents. 12875 12876@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 12877@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f1} 12878@subsection No_Task_At_Interrupt_Priority 12879 12880 12881@geindex No_Task_At_Interrupt_Priority 12882 12883[GNAT] This restriction ensures at compile time that there is no 12884Interrupt_Priority aspect or pragma for a task or a task type. As 12885a consequence, the tasks are always created with a priority below 12886that an interrupt priority. 12887 12888@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 12889@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f2} 12890@subsection No_Task_Attributes_Package 12891 12892 12893@geindex No_Task_Attributes_Package 12894 12895[GNAT] This restriction ensures at compile time that there are no implicit or 12896explicit dependencies on the package @code{Ada.Task_Attributes}. 12897 12898@geindex No_Task_Attributes 12899 12900The restriction @code{No_Task_Attributes} is recognized as a synonym 12901for @code{No_Task_Attributes_Package}. This is retained for historical 12902compatibility purposes (and a warning will be generated for its use if 12903warnings on obsolescent features are activated). 12904 12905@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 12906@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f3} 12907@subsection No_Task_Hierarchy 12908 12909 12910@geindex No_Task_Hierarchy 12911 12912[RM D.7] All (non-environment) tasks depend 12913directly on the environment task of the partition. 12914 12915@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 12916@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f4} 12917@subsection No_Task_Termination 12918 12919 12920@geindex No_Task_Termination 12921 12922[RM D.7] Tasks that terminate are erroneous. 12923 12924@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 12925@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1f5} 12926@subsection No_Tasking 12927 12928 12929@geindex No_Tasking 12930 12931[GNAT] This restriction prevents the declaration of tasks or task types 12932throughout the partition. It is similar in effect to the use of 12933@code{Max_Tasks => 0} except that violations are caught at compile time 12934and cause an error message to be output either by the compiler or 12935binder. 12936 12937@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 12938@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1f6} 12939@subsection No_Terminate_Alternatives 12940 12941 12942@geindex No_Terminate_Alternatives 12943 12944[RM D.7] There are no selective accepts with terminate alternatives. 12945 12946@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 12947@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1f7} 12948@subsection No_Unchecked_Access 12949 12950 12951@geindex No_Unchecked_Access 12952 12953[RM H.4] This restriction ensures at compile time that there are no 12954occurrences of the Unchecked_Access attribute. 12955 12956@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 12957@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1f8} 12958@subsection No_Unchecked_Conversion 12959 12960 12961@geindex No_Unchecked_Conversion 12962 12963[RM J.13] This restriction ensures at compile time that there are no semantic 12964dependences on the predefined generic function Unchecked_Conversion. 12965 12966@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 12967@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1f9} 12968@subsection No_Unchecked_Deallocation 12969 12970 12971@geindex No_Unchecked_Deallocation 12972 12973[RM J.13] This restriction ensures at compile time that there are no semantic 12974dependences on the predefined generic procedure Unchecked_Deallocation. 12975 12976@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 12977@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1fa} 12978@subsection No_Use_Of_Entity 12979 12980 12981@geindex No_Use_Of_Entity 12982 12983[GNAT] This restriction ensures at compile time that there are no references 12984to the entity given in the form 12985 12986@example 12987No_Use_Of_Entity => Name 12988@end example 12989 12990where @code{Name} is the fully qualified entity, for example 12991 12992@example 12993No_Use_Of_Entity => Ada.Text_IO.Put_Line 12994@end example 12995 12996@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 12997@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1fb} 12998@subsection Pure_Barriers 12999 13000 13001@geindex Pure_Barriers 13002 13003[GNAT] This restriction ensures at compile time that protected entry 13004barriers are restricted to: 13005 13006 13007@itemize * 13008 13009@item 13010components of the protected object (excluding selection from dereferences), 13011 13012@item 13013constant declarations, 13014 13015@item 13016named numbers, 13017 13018@item 13019enumeration literals, 13020 13021@item 13022integer literals, 13023 13024@item 13025real literals, 13026 13027@item 13028character literals, 13029 13030@item 13031implicitly defined comparison operators, 13032 13033@item 13034uses of the Standard."not" operator, 13035 13036@item 13037short-circuit operator, 13038 13039@item 13040the Count attribute 13041@end itemize 13042 13043This restriction is a relaxation of the Simple_Barriers restriction, 13044but still ensures absence of side effects, exceptions, and recursion 13045during the evaluation of the barriers. 13046 13047@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 13048@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{1fc} 13049@subsection Simple_Barriers 13050 13051 13052@geindex Simple_Barriers 13053 13054[RM D.7] This restriction ensures at compile time that barriers in entry 13055declarations for protected types are restricted to either static boolean 13056expressions or references to simple boolean variables defined in the private 13057part of the protected type. No other form of entry barriers is permitted. 13058 13059@geindex Boolean_Entry_Barriers 13060 13061The restriction @code{Boolean_Entry_Barriers} is recognized as a 13062synonym for @code{Simple_Barriers}. This is retained for historical 13063compatibility purposes (and a warning will be generated for its use if 13064warnings on obsolescent features are activated). 13065 13066@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 13067@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{1fd} 13068@subsection Static_Priorities 13069 13070 13071@geindex Static_Priorities 13072 13073[GNAT] This restriction ensures at compile time that all priority expressions 13074are static, and that there are no dependences on the package 13075@code{Ada.Dynamic_Priorities}. 13076 13077@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 13078@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{1fe} 13079@subsection Static_Storage_Size 13080 13081 13082@geindex Static_Storage_Size 13083 13084[GNAT] This restriction ensures at compile time that any expression appearing 13085in a Storage_Size pragma or attribute definition clause is static. 13086 13087@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 13088@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{1ff}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{200} 13089@section Program Unit Level Restrictions 13090 13091 13092The second set of restriction identifiers 13093does not require partition-wide consistency. 13094The restriction may be enforced for a single 13095compilation unit without any effect on any of the 13096other compilation units in the partition. 13097 13098@menu 13099* No_Elaboration_Code:: 13100* No_Dynamic_Sized_Objects:: 13101* No_Entry_Queue:: 13102* No_Implementation_Aspect_Specifications:: 13103* No_Implementation_Attributes:: 13104* No_Implementation_Identifiers:: 13105* No_Implementation_Pragmas:: 13106* No_Implementation_Restrictions:: 13107* No_Implementation_Units:: 13108* No_Implicit_Aliasing:: 13109* No_Implicit_Loops:: 13110* No_Obsolescent_Features:: 13111* No_Wide_Characters:: 13112* Static_Dispatch_Tables:: 13113* SPARK_05:: 13114 13115@end menu 13116 13117@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions 13118@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{201} 13119@subsection No_Elaboration_Code 13120 13121 13122@geindex No_Elaboration_Code 13123 13124[GNAT] This restriction ensures at compile time that no elaboration code is 13125generated. Note that this is not the same condition as is enforced 13126by pragma @code{Preelaborate}. There are cases in which pragma 13127@code{Preelaborate} still permits code to be generated (e.g., code 13128to initialize a large array to all zeroes), and there are cases of units 13129which do not meet the requirements for pragma @code{Preelaborate}, 13130but for which no elaboration code is generated. Generally, it is 13131the case that preelaborable units will meet the restrictions, with 13132the exception of large aggregates initialized with an others_clause, 13133and exception declarations (which generate calls to a run-time 13134registry procedure). This restriction is enforced on 13135a unit by unit basis, it need not be obeyed consistently 13136throughout a partition. 13137 13138In the case of aggregates with others, if the aggregate has a dynamic 13139size, there is no way to eliminate the elaboration code (such dynamic 13140bounds would be incompatible with @code{Preelaborate} in any case). If 13141the bounds are static, then use of this restriction actually modifies 13142the code choice of the compiler to avoid generating a loop, and instead 13143generate the aggregate statically if possible, no matter how many times 13144the data for the others clause must be repeatedly generated. 13145 13146It is not possible to precisely document 13147the constructs which are compatible with this restriction, since, 13148unlike most other restrictions, this is not a restriction on the 13149source code, but a restriction on the generated object code. For 13150example, if the source contains a declaration: 13151 13152@example 13153Val : constant Integer := X; 13154@end example 13155 13156where X is not a static constant, it may be possible, depending 13157on complex optimization circuitry, for the compiler to figure 13158out the value of X at compile time, in which case this initialization 13159can be done by the loader, and requires no initialization code. It 13160is not possible to document the precise conditions under which the 13161optimizer can figure this out. 13162 13163Note that this the implementation of this restriction requires full 13164code generation. If it is used in conjunction with "semantics only" 13165checking, then some cases of violations may be missed. 13166 13167When this restriction is active, we are not requesting control-flow 13168preservation with -fpreserve-control-flow, and the static elaboration model is 13169used, the compiler is allowed to suppress the elaboration counter normally 13170associated with the unit. This counter is typically used to check for access 13171before elaboration and to control multiple elaboration attempts. 13172 13173@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions 13174@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{202} 13175@subsection No_Dynamic_Sized_Objects 13176 13177 13178@geindex No_Dynamic_Sized_Objects 13179 13180[GNAT] This restriction disallows certain constructs that might lead to the 13181creation of dynamic-sized composite objects (or array or discriminated type). 13182An array subtype indication is illegal if the bounds are not static 13183or references to discriminants of an enclosing type. 13184A discriminated subtype indication is illegal if the type has 13185discriminant-dependent array components or a variant part, and the 13186discriminants are not static. In addition, array and record aggregates are 13187illegal in corresponding cases. Note that this restriction does not forbid 13188access discriminants. It is often a good idea to combine this restriction 13189with No_Secondary_Stack. 13190 13191@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 13192@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{203} 13193@subsection No_Entry_Queue 13194 13195 13196@geindex No_Entry_Queue 13197 13198[GNAT] This restriction is a declaration that any protected entry compiled in 13199the scope of the restriction has at most one task waiting on the entry 13200at any one time, and so no queue is required. This restriction is not 13201checked at compile time. A program execution is erroneous if an attempt 13202is made to queue a second task on such an entry. 13203 13204@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 13205@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{204} 13206@subsection No_Implementation_Aspect_Specifications 13207 13208 13209@geindex No_Implementation_Aspect_Specifications 13210 13211[RM 13.12.1] This restriction checks at compile time that no 13212GNAT-defined aspects are present. With this restriction, the only 13213aspects that can be used are those defined in the Ada Reference Manual. 13214 13215@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 13216@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{205} 13217@subsection No_Implementation_Attributes 13218 13219 13220@geindex No_Implementation_Attributes 13221 13222[RM 13.12.1] This restriction checks at compile time that no 13223GNAT-defined attributes are present. With this restriction, the only 13224attributes that can be used are those defined in the Ada Reference 13225Manual. 13226 13227@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 13228@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{206} 13229@subsection No_Implementation_Identifiers 13230 13231 13232@geindex No_Implementation_Identifiers 13233 13234[RM 13.12.1] This restriction checks at compile time that no 13235implementation-defined identifiers (marked with pragma Implementation_Defined) 13236occur within language-defined packages. 13237 13238@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 13239@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{207} 13240@subsection No_Implementation_Pragmas 13241 13242 13243@geindex No_Implementation_Pragmas 13244 13245[RM 13.12.1] This restriction checks at compile time that no 13246GNAT-defined pragmas are present. With this restriction, the only 13247pragmas that can be used are those defined in the Ada Reference Manual. 13248 13249@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 13250@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{208} 13251@subsection No_Implementation_Restrictions 13252 13253 13254@geindex No_Implementation_Restrictions 13255 13256[GNAT] This restriction checks at compile time that no GNAT-defined restriction 13257identifiers (other than @code{No_Implementation_Restrictions} itself) 13258are present. With this restriction, the only other restriction identifiers 13259that can be used are those defined in the Ada Reference Manual. 13260 13261@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 13262@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{209} 13263@subsection No_Implementation_Units 13264 13265 13266@geindex No_Implementation_Units 13267 13268[RM 13.12.1] This restriction checks at compile time that there is no 13269mention in the context clause of any implementation-defined descendants 13270of packages Ada, Interfaces, or System. 13271 13272@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions 13273@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{20a} 13274@subsection No_Implicit_Aliasing 13275 13276 13277@geindex No_Implicit_Aliasing 13278 13279[GNAT] This restriction, which is not required to be partition-wide consistent, 13280requires an explicit aliased keyword for an object to which 'Access, 13281'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 13282the 'Unrestricted_Access attribute for objects. Note: the reason that 13283Unrestricted_Access is forbidden is that it would require the prefix 13284to be aliased, and in such cases, it can always be replaced by 13285the standard attribute Unchecked_Access which is preferable. 13286 13287@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions 13288@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{20b} 13289@subsection No_Implicit_Loops 13290 13291 13292@geindex No_Implicit_Loops 13293 13294[GNAT] This restriction ensures that the generated code of the unit marked 13295with this restriction does not contain any implicit @code{for} loops, either by 13296modifying the generated code where possible, or by rejecting any construct 13297that would otherwise generate an implicit @code{for} loop. If this restriction is 13298active, it is possible to build large array aggregates with all static 13299components without generating an intermediate temporary, and without generating 13300a loop to initialize individual components. Otherwise, a loop is created for 13301arrays larger than about 5000 scalar components. Note that if this restriction 13302is set in the spec of a package, it will not apply to its body. 13303 13304@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions 13305@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{20c} 13306@subsection No_Obsolescent_Features 13307 13308 13309@geindex No_Obsolescent_Features 13310 13311[RM 13.12.1] This restriction checks at compile time that no obsolescent 13312features are used, as defined in Annex J of the Ada Reference Manual. 13313 13314@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions 13315@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{20d} 13316@subsection No_Wide_Characters 13317 13318 13319@geindex No_Wide_Characters 13320 13321[GNAT] This restriction ensures at compile time that no uses of the types 13322@code{Wide_Character} or @code{Wide_String} or corresponding wide 13323wide types 13324appear, and that no wide or wide wide string or character literals 13325appear in the program (that is literals representing characters not in 13326type @code{Character}). 13327 13328@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions 13329@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{20e} 13330@subsection Static_Dispatch_Tables 13331 13332 13333@geindex Static_Dispatch_Tables 13334 13335[GNAT] This restriction checks at compile time that all the artifacts 13336associated with dispatch tables can be placed in read-only memory. 13337 13338@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions 13339@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{20f} 13340@subsection SPARK_05 13341 13342 13343@geindex SPARK_05 13344 13345[GNAT] This restriction checks at compile time that some constructs forbidden 13346in SPARK 2005 are not present. Note that SPARK 2005 has been superseded by 13347SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that 13348a codebase respects SPARK 2014 restrictions, mark the code with pragma or 13349aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as 13350follows: 13351 13352@example 13353gnatprove -P project.gpr --mode=stone 13354@end example 13355 13356or equivalently: 13357 13358@example 13359gnatprove -P project.gpr --mode=check_all 13360@end example 13361 13362With restriction @code{SPARK_05}, error messages related to SPARK 2005 restriction 13363have the form: 13364 13365@example 13366violation of restriction "SPARK_05" at <source-location> 13367 <error message> 13368@end example 13369 13370@geindex SPARK 13371 13372The restriction @code{SPARK} is recognized as a synonym for @code{SPARK_05}. This is 13373retained for historical compatibility purposes (and an unconditional warning 13374will be generated for its use, advising replacement by @code{SPARK_05}). 13375 13376This is not a replacement for the semantic checks performed by the 13377SPARK Examiner tool, as the compiler currently only deals with code, 13378not SPARK 2005 annotations, and does not guarantee catching all 13379cases of constructs forbidden by SPARK 2005. 13380 13381Thus it may well be the case that code which passes the compiler with 13382the SPARK 2005 restriction is rejected by the SPARK Examiner, e.g. due to 13383the different visibility rules of the Examiner based on SPARK 2005 13384@code{inherit} annotations. 13385 13386This restriction can be useful in providing an initial filter for code 13387developed using SPARK 2005, or in examining legacy code to see how far 13388it is from meeting SPARK 2005 restrictions. 13389 13390The list below summarizes the checks that are performed when this 13391restriction is in force: 13392 13393 13394@itemize * 13395 13396@item 13397No block statements 13398 13399@item 13400No case statements with only an others clause 13401 13402@item 13403Exit statements in loops must respect the SPARK 2005 language restrictions 13404 13405@item 13406No goto statements 13407 13408@item 13409Return can only appear as last statement in function 13410 13411@item 13412Function must have return statement 13413 13414@item 13415Loop parameter specification must include subtype mark 13416 13417@item 13418Prefix of expanded name cannot be a loop statement 13419 13420@item 13421Abstract subprogram not allowed 13422 13423@item 13424User-defined operators not allowed 13425 13426@item 13427Access type parameters not allowed 13428 13429@item 13430Default expressions for parameters not allowed 13431 13432@item 13433Default expressions for record fields not allowed 13434 13435@item 13436No tasking constructs allowed 13437 13438@item 13439Label needed at end of subprograms and packages 13440 13441@item 13442No mixing of positional and named parameter association 13443 13444@item 13445No access types as result type 13446 13447@item 13448No unconstrained arrays as result types 13449 13450@item 13451No null procedures 13452 13453@item 13454Initial and later declarations must be in correct order (declaration can't come after body) 13455 13456@item 13457No attributes on private types if full declaration not visible 13458 13459@item 13460No package declaration within package specification 13461 13462@item 13463No controlled types 13464 13465@item 13466No discriminant types 13467 13468@item 13469No overloading 13470 13471@item 13472Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed) 13473 13474@item 13475Access attribute not allowed 13476 13477@item 13478Allocator not allowed 13479 13480@item 13481Result of catenation must be String 13482 13483@item 13484Operands of catenation must be string literal, static char or another catenation 13485 13486@item 13487No conditional expressions 13488 13489@item 13490No explicit dereference 13491 13492@item 13493Quantified expression not allowed 13494 13495@item 13496Slicing not allowed 13497 13498@item 13499No exception renaming 13500 13501@item 13502No generic renaming 13503 13504@item 13505No object renaming 13506 13507@item 13508No use clause 13509 13510@item 13511Aggregates must be qualified 13512 13513@item 13514Nonstatic choice in array aggregates not allowed 13515 13516@item 13517The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type 13518 13519@item 13520No mixing of positional and named association in aggregate, no multi choice 13521 13522@item 13523AND, OR and XOR for arrays only allowed when operands have same static bounds 13524 13525@item 13526Fixed point operands to * or / must be qualified or converted 13527 13528@item 13529Comparison operators not allowed for Booleans or arrays (except strings) 13530 13531@item 13532Equality not allowed for arrays with non-matching static bounds (except strings) 13533 13534@item 13535Conversion / qualification not allowed for arrays with non-matching static bounds 13536 13537@item 13538Subprogram declaration only allowed in package spec (unless followed by import) 13539 13540@item 13541Access types not allowed 13542 13543@item 13544Incomplete type declaration not allowed 13545 13546@item 13547Object and subtype declarations must respect SPARK 2005 restrictions 13548 13549@item 13550Digits or delta constraint not allowed 13551 13552@item 13553Decimal fixed point type not allowed 13554 13555@item 13556Aliasing of objects not allowed 13557 13558@item 13559Modular type modulus must be power of 2 13560 13561@item 13562Base not allowed on subtype mark 13563 13564@item 13565Unary operators not allowed on modular types (except not) 13566 13567@item 13568Untagged record cannot be null 13569 13570@item 13571No class-wide operations 13572 13573@item 13574Initialization expressions must respect SPARK 2005 restrictions 13575 13576@item 13577Nonstatic ranges not allowed except in iteration schemes 13578 13579@item 13580String subtypes must have lower bound of 1 13581 13582@item 13583Subtype of Boolean cannot have constraint 13584 13585@item 13586At most one tagged type or extension per package 13587 13588@item 13589Interface is not allowed 13590 13591@item 13592Character literal cannot be prefixed (selector name cannot be character literal) 13593 13594@item 13595Record aggregate cannot contain 'others' 13596 13597@item 13598Component association in record aggregate must contain a single choice 13599 13600@item 13601Ancestor part cannot be a type mark 13602 13603@item 13604Attributes 'Image, 'Width and 'Value not allowed 13605 13606@item 13607Functions may not update globals 13608 13609@item 13610Subprograms may not contain direct calls to themselves (prevents recursion within unit) 13611 13612@item 13613Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit) 13614@end itemize 13615 13616The following restrictions are enforced, but note that they are actually more 13617strict that the latest SPARK 2005 language definition: 13618 13619 13620@itemize * 13621 13622@item 13623No derived types other than tagged type extensions 13624 13625@item 13626Subtype of unconstrained array must have constraint 13627@end itemize 13628 13629This list summarises the main SPARK 2005 language rules that are not 13630currently checked by the SPARK_05 restriction: 13631 13632 13633@itemize * 13634 13635@item 13636SPARK 2005 annotations are treated as comments so are not checked at all 13637 13638@item 13639Based real literals not allowed 13640 13641@item 13642Objects cannot be initialized at declaration by calls to user-defined functions 13643 13644@item 13645Objects cannot be initialized at declaration by assignments from variables 13646 13647@item 13648Objects cannot be initialized at declaration by assignments from indexed/selected components 13649 13650@item 13651Ranges shall not be null 13652 13653@item 13654A fixed point delta expression must be a simple expression 13655 13656@item 13657Restrictions on where renaming declarations may be placed 13658 13659@item 13660Externals of mode 'out' cannot be referenced 13661 13662@item 13663Externals of mode 'in' cannot be updated 13664 13665@item 13666Loop with no iteration scheme or exits only allowed as last statement in main program or task 13667 13668@item 13669Subprogram cannot have parent unit name 13670 13671@item 13672SPARK 2005 inherited subprogram must be prefixed with overriding 13673 13674@item 13675External variables (or functions that reference them) may not be passed as actual parameters 13676 13677@item 13678Globals must be explicitly mentioned in contract 13679 13680@item 13681Deferred constants cannot be completed by pragma Import 13682 13683@item 13684Package initialization cannot read/write variables from other packages 13685 13686@item 13687Prefix not allowed for entities that are directly visible 13688 13689@item 13690Identifier declaration can't override inherited package name 13691 13692@item 13693Cannot use Standard or other predefined packages as identifiers 13694 13695@item 13696After renaming, cannot use the original name 13697 13698@item 13699Subprograms can only be renamed to remove package prefix 13700 13701@item 13702Pragma import must be immediately after entity it names 13703 13704@item 13705No mutual recursion between multiple units (this can be checked with gnatcheck) 13706@end itemize 13707 13708Note that if a unit is compiled in Ada 95 mode with the SPARK 2005 restriction, 13709violations will be reported for constructs forbidden in SPARK 95, 13710instead of SPARK 2005. 13711 13712@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13713@anchor{gnat_rm/implementation_advice doc}@anchor{210}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{211} 13714@chapter Implementation Advice 13715 13716 13717The main text of the Ada Reference Manual describes the required 13718behavior of all Ada compilers, and the GNAT compiler conforms to 13719these requirements. 13720 13721In addition, there are sections throughout the Ada Reference Manual headed 13722by the phrase 'Implementation advice'. These sections are not normative, 13723i.e., they do not specify requirements that all compilers must 13724follow. Rather they provide advice on generally desirable behavior. 13725They are not requirements, because they describe behavior that cannot 13726be provided on all systems, or may be undesirable on some systems. 13727 13728As far as practical, GNAT follows the implementation advice in 13729the Ada Reference Manual. Each such RM section corresponds to a section 13730in this chapter whose title specifies the 13731RM section number and paragraph number and the subject of 13732the advice. The contents of each section consists of the RM text within 13733quotation marks, 13734followed by the GNAT interpretation of the advice. Most often, this simply says 13735'followed', which means that GNAT follows the advice. However, in a 13736number of cases, GNAT deliberately deviates from this advice, in which 13737case the text describes what GNAT does and why. 13738 13739@geindex Error detection 13740 13741@menu 13742* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13743* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13744* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13745* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13746* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13747* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13748* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13749* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13750* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13751* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13752* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13753* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 13754* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13755* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13756* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13757* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13758* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13759* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13760* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13761* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13762* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13763* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13764* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13765* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13766* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13767* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13768* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13769* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13770* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13771* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13772* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13773* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 13774* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13775* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13776* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13777* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13778* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13779* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13780* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13781* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13782* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13783* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13784* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13785* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13786* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13787* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13788* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13789* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13790* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13791* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13792* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13793* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13794* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13795* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13796* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13797* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13798* RM F(7); COBOL Support: RM F 7 COBOL Support. 13799* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13800* RM G; Numerics: RM G Numerics. 13801* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13802* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13803* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13804* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13805* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13806 13807@end menu 13808 13809@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13810@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{212} 13811@section RM 1.1.3(20): Error Detection 13812 13813 13814@quotation 13815 13816"If an implementation detects the use of an unsupported Specialized Needs 13817Annex feature at run time, it should raise @code{Program_Error} if 13818feasible." 13819@end quotation 13820 13821Not relevant. All specialized needs annex features are either supported, 13822or diagnosed at compile time. 13823 13824@geindex Child Units 13825 13826@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13827@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{213} 13828@section RM 1.1.3(31): Child Units 13829 13830 13831@quotation 13832 13833"If an implementation wishes to provide implementation-defined 13834extensions to the functionality of a language-defined library unit, it 13835should normally do so by adding children to the library unit." 13836@end quotation 13837 13838Followed. 13839 13840@geindex Bounded errors 13841 13842@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13843@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{214} 13844@section RM 1.1.5(12): Bounded Errors 13845 13846 13847@quotation 13848 13849"If an implementation detects a bounded error or erroneous 13850execution, it should raise @code{Program_Error}." 13851@end quotation 13852 13853Followed in all cases in which the implementation detects a bounded 13854error or erroneous execution. Not all such situations are detected at 13855runtime. 13856 13857@geindex Pragmas 13858 13859@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13860@anchor{gnat_rm/implementation_advice id2}@anchor{215}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{216} 13861@section RM 2.8(16): Pragmas 13862 13863 13864@quotation 13865 13866"Normally, implementation-defined pragmas should have no semantic effect 13867for error-free programs; that is, if the implementation-defined pragmas 13868are removed from a working program, the program should still be legal, 13869and should still have the same semantics." 13870@end quotation 13871 13872The following implementation defined pragmas are exceptions to this 13873rule: 13874 13875 13876@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 13877@headitem 13878 13879Pragma 13880 13881@tab 13882 13883Explanation 13884 13885@item 13886 13887@emph{Abort_Defer} 13888 13889@tab 13890 13891Affects semantics 13892 13893@item 13894 13895@emph{Ada_83} 13896 13897@tab 13898 13899Affects legality 13900 13901@item 13902 13903@emph{Assert} 13904 13905@tab 13906 13907Affects semantics 13908 13909@item 13910 13911@emph{CPP_Class} 13912 13913@tab 13914 13915Affects semantics 13916 13917@item 13918 13919@emph{CPP_Constructor} 13920 13921@tab 13922 13923Affects semantics 13924 13925@item 13926 13927@emph{Debug} 13928 13929@tab 13930 13931Affects semantics 13932 13933@item 13934 13935@emph{Interface_Name} 13936 13937@tab 13938 13939Affects semantics 13940 13941@item 13942 13943@emph{Machine_Attribute} 13944 13945@tab 13946 13947Affects semantics 13948 13949@item 13950 13951@emph{Unimplemented_Unit} 13952 13953@tab 13954 13955Affects legality 13956 13957@item 13958 13959@emph{Unchecked_Union} 13960 13961@tab 13962 13963Affects semantics 13964 13965@end multitable 13966 13967 13968In each of the above cases, it is essential to the purpose of the pragma 13969that this advice not be followed. For details see 13970@ref{7,,Implementation Defined Pragmas}. 13971 13972@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 13973@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{217} 13974@section RM 2.8(17-19): Pragmas 13975 13976 13977@quotation 13978 13979"Normally, an implementation should not define pragmas that can 13980make an illegal program legal, except as follows: 13981 13982 13983@itemize * 13984 13985@item 13986A pragma used to complete a declaration, such as a pragma @code{Import}; 13987 13988@item 13989A pragma used to configure the environment by adding, removing, or 13990replacing @code{library_items}." 13991@end itemize 13992@end quotation 13993 13994See @ref{216,,RM 2.8(16); Pragmas}. 13995 13996@geindex Character Sets 13997 13998@geindex Alternative Character Sets 13999 14000@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 14001@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{218} 14002@section RM 3.5.2(5): Alternative Character Sets 14003 14004 14005@quotation 14006 14007"If an implementation supports a mode with alternative interpretations 14008for @code{Character} and @code{Wide_Character}, the set of graphic 14009characters of @code{Character} should nevertheless remain a proper 14010subset of the set of graphic characters of @code{Wide_Character}. Any 14011character set 'localizations' should be reflected in the results of 14012the subprograms defined in the language-defined package 14013@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 14014an alternative interpretation of @code{Character}, the implementation should 14015also support a corresponding change in what is a legal 14016@code{identifier_letter}." 14017@end quotation 14018 14019Not all wide character modes follow this advice, in particular the JIS 14020and IEC modes reflect standard usage in Japan, and in these encoding, 14021the upper half of the Latin-1 set is not part of the wide-character 14022subset, since the most significant bit is used for wide character 14023encoding. However, this only applies to the external forms. Internally 14024there is no such restriction. 14025 14026@geindex Integer types 14027 14028@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 14029@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{219} 14030@section RM 3.5.4(28): Integer Types 14031 14032 14033@quotation 14034 14035"An implementation should support @code{Long_Integer} in addition to 14036@code{Integer} if the target machine supports 32-bit (or longer) 14037arithmetic. No other named integer subtypes are recommended for package 14038@code{Standard}. Instead, appropriate named integer subtypes should be 14039provided in the library package @code{Interfaces} (see B.2)." 14040@end quotation 14041 14042@code{Long_Integer} is supported. Other standard integer types are supported 14043so this advice is not fully followed. These types 14044are supported for convenient interface to C, and so that all hardware 14045types of the machine are easily available. 14046 14047@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 14048@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{21a} 14049@section RM 3.5.4(29): Integer Types 14050 14051 14052@quotation 14053 14054"An implementation for a two's complement machine should support 14055modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 14056implementation should support a non-binary modules up to @code{Integer'Last}." 14057@end quotation 14058 14059Followed. 14060 14061@geindex Enumeration values 14062 14063@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 14064@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{21b} 14065@section RM 3.5.5(8): Enumeration Values 14066 14067 14068@quotation 14069 14070"For the evaluation of a call on @code{S'Pos} for an enumeration 14071subtype, if the value of the operand does not correspond to the internal 14072code for any enumeration literal of its type (perhaps due to an 14073un-initialized variable), then the implementation should raise 14074@code{Program_Error}. This is particularly important for enumeration 14075types with noncontiguous internal codes specified by an 14076enumeration_representation_clause." 14077@end quotation 14078 14079Followed. 14080 14081@geindex Float types 14082 14083@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 14084@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{21c} 14085@section RM 3.5.7(17): Float Types 14086 14087 14088@quotation 14089 14090"An implementation should support @code{Long_Float} in addition to 14091@code{Float} if the target machine supports 11 or more digits of 14092precision. No other named floating point subtypes are recommended for 14093package @code{Standard}. Instead, appropriate named floating point subtypes 14094should be provided in the library package @code{Interfaces} (see B.2)." 14095@end quotation 14096 14097@code{Short_Float} and @code{Long_Long_Float} are also provided. The 14098former provides improved compatibility with other implementations 14099supporting this type. The latter corresponds to the highest precision 14100floating-point type supported by the hardware. On most machines, this 14101will be the same as @code{Long_Float}, but on some machines, it will 14102correspond to the IEEE extended form. The notable case is all ia32 14103(x86) implementations, where @code{Long_Long_Float} corresponds to 14104the 80-bit extended precision format supported in hardware on this 14105processor. Note that the 128-bit format on SPARC is not supported, 14106since this is a software rather than a hardware format. 14107 14108@geindex Multidimensional arrays 14109 14110@geindex Arrays 14111@geindex multidimensional 14112 14113@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice 14114@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{21d} 14115@section RM 3.6.2(11): Multidimensional Arrays 14116 14117 14118@quotation 14119 14120"An implementation should normally represent multidimensional arrays in 14121row-major order, consistent with the notation used for multidimensional 14122array aggregates (see 4.3.3). However, if a pragma @code{Convention} 14123(@code{Fortran}, ...) applies to a multidimensional array type, then 14124column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})." 14125@end quotation 14126 14127Followed. 14128 14129@geindex Duration'Small 14130 14131@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 14132@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{21e} 14133@section RM 9.6(30-31): Duration'Small 14134 14135 14136@quotation 14137 14138"Whenever possible in an implementation, the value of @code{Duration'Small} 14139should be no greater than 100 microseconds." 14140@end quotation 14141 14142Followed. (@code{Duration'Small} = 10**(-9)). 14143 14144@quotation 14145 14146"The time base for @code{delay_relative_statements} should be monotonic; 14147it need not be the same time base as used for @code{Calendar.Clock}." 14148@end quotation 14149 14150Followed. 14151 14152@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice 14153@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{21f} 14154@section RM 10.2.1(12): Consistent Representation 14155 14156 14157@quotation 14158 14159"In an implementation, a type declared in a pre-elaborated package should 14160have the same representation in every elaboration of a given version of 14161the package, whether the elaborations occur in distinct executions of 14162the same program, or in executions of distinct programs or partitions 14163that include the given version." 14164@end quotation 14165 14166Followed, except in the case of tagged types. Tagged types involve 14167implicit pointers to a local copy of a dispatch table, and these pointers 14168have representations which thus depend on a particular elaboration of the 14169package. It is not easy to see how it would be possible to follow this 14170advice without severely impacting efficiency of execution. 14171 14172@geindex Exception information 14173 14174@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 14175@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{220} 14176@section RM 11.4.1(19): Exception Information 14177 14178 14179@quotation 14180 14181"@code{Exception_Message} by default and @code{Exception_Information} 14182should produce information useful for 14183debugging. @code{Exception_Message} should be short, about one 14184line. @code{Exception_Information} can be long. @code{Exception_Message} 14185should not include the 14186@code{Exception_Name}. @code{Exception_Information} should include both 14187the @code{Exception_Name} and the @code{Exception_Message}." 14188@end quotation 14189 14190Followed. For each exception that doesn't have a specified 14191@code{Exception_Message}, the compiler generates one containing the location 14192of the raise statement. This location has the form 'file_name:line', where 14193file_name is the short file name (without path information) and line is the line 14194number in the file. Note that in the case of the Zero Cost Exception 14195mechanism, these messages become redundant with the Exception_Information that 14196contains a full backtrace of the calling sequence, so they are disabled. 14197To disable explicitly the generation of the source location message, use the 14198Pragma @code{Discard_Names}. 14199 14200@geindex Suppression of checks 14201 14202@geindex Checks 14203@geindex suppression of 14204 14205@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 14206@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{221} 14207@section RM 11.5(28): Suppression of Checks 14208 14209 14210@quotation 14211 14212"The implementation should minimize the code executed for checks that 14213have been suppressed." 14214@end quotation 14215 14216Followed. 14217 14218@geindex Representation clauses 14219 14220@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 14221@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{222} 14222@section RM 13.1 (21-24): Representation Clauses 14223 14224 14225@quotation 14226 14227"The recommended level of support for all representation items is 14228qualified as follows: 14229 14230An implementation need not support representation items containing 14231nonstatic expressions, except that an implementation should support a 14232representation item for a given entity if each nonstatic expression in 14233the representation item is a name that statically denotes a constant 14234declared before the entity." 14235@end quotation 14236 14237Followed. In fact, GNAT goes beyond the recommended level of support 14238by allowing nonstatic expressions in some representation clauses even 14239without the need to declare constants initialized with the values of 14240such expressions. 14241For example: 14242 14243@example 14244 X : Integer; 14245 Y : Float; 14246 for Y'Address use X'Address;>> 14247 14248 14249"An implementation need not support a specification for the `@w{`}Size`@w{`} 14250for a given composite subtype, nor the size or storage place for an 14251object (including a component) of a given composite subtype, unless the 14252constraints on the subtype and its composite subcomponents (if any) are 14253all static constraints." 14254@end example 14255 14256Followed. Size Clauses are not permitted on nonstatic components, as 14257described above. 14258 14259@quotation 14260 14261"An aliased component, or a component whose type is by-reference, should 14262always be allocated at an addressable location." 14263@end quotation 14264 14265Followed. 14266 14267@geindex Packed types 14268 14269@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 14270@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{223} 14271@section RM 13.2(6-8): Packed Types 14272 14273 14274@quotation 14275 14276"If a type is packed, then the implementation should try to minimize 14277storage allocated to objects of the type, possibly at the expense of 14278speed of accessing components, subject to reasonable complexity in 14279addressing calculations. 14280 14281The recommended level of support pragma @code{Pack} is: 14282 14283For a packed record type, the components should be packed as tightly as 14284possible subject to the Sizes of the component subtypes, and subject to 14285any @emph{record_representation_clause} that applies to the type; the 14286implementation may, but need not, reorder components or cross aligned 14287word boundaries to improve the packing. A component whose @code{Size} is 14288greater than the word size may be allocated an integral number of words." 14289@end quotation 14290 14291Followed. Tight packing of arrays is supported for all component sizes 14292up to 64-bits. If the array component size is 1 (that is to say, if 14293the component is a boolean type or an enumeration type with two values) 14294then values of the type are implicitly initialized to zero. This 14295happens both for objects of the packed type, and for objects that have a 14296subcomponent of the packed type. 14297 14298@quotation 14299 14300"An implementation should support Address clauses for imported 14301subprograms." 14302@end quotation 14303 14304Followed. 14305 14306@geindex Address clauses 14307 14308@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 14309@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{224} 14310@section RM 13.3(14-19): Address Clauses 14311 14312 14313@quotation 14314 14315"For an array @code{X}, @code{X'Address} should point at the first 14316component of the array, and not at the array bounds." 14317@end quotation 14318 14319Followed. 14320 14321@quotation 14322 14323"The recommended level of support for the @code{Address} attribute is: 14324 14325@code{X'Address} should produce a useful result if @code{X} is an 14326object that is aliased or of a by-reference type, or is an entity whose 14327@code{Address} has been specified." 14328@end quotation 14329 14330Followed. A valid address will be produced even if none of those 14331conditions have been met. If necessary, the object is forced into 14332memory to ensure the address is valid. 14333 14334@quotation 14335 14336"An implementation should support @code{Address} clauses for imported 14337subprograms." 14338@end quotation 14339 14340Followed. 14341 14342@quotation 14343 14344"Objects (including subcomponents) that are aliased or of a by-reference 14345type should be allocated on storage element boundaries." 14346@end quotation 14347 14348Followed. 14349 14350@quotation 14351 14352"If the @code{Address} of an object is specified, or it is imported or exported, 14353then the implementation should not perform optimizations based on 14354assumptions of no aliases." 14355@end quotation 14356 14357Followed. 14358 14359@geindex Alignment clauses 14360 14361@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 14362@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{225} 14363@section RM 13.3(29-35): Alignment Clauses 14364 14365 14366@quotation 14367 14368"The recommended level of support for the @code{Alignment} attribute for 14369subtypes is: 14370 14371An implementation should support specified Alignments that are factors 14372and multiples of the number of storage elements per word, subject to the 14373following:" 14374@end quotation 14375 14376Followed. 14377 14378@quotation 14379 14380"An implementation need not support specified Alignments for 14381combinations of Sizes and Alignments that cannot be easily 14382loaded and stored by available machine instructions." 14383@end quotation 14384 14385Followed. 14386 14387@quotation 14388 14389"An implementation need not support specified Alignments that are 14390greater than the maximum @code{Alignment} the implementation ever returns by 14391default." 14392@end quotation 14393 14394Followed. 14395 14396@quotation 14397 14398"The recommended level of support for the @code{Alignment} attribute for 14399objects is: 14400 14401Same as above, for subtypes, but in addition:" 14402@end quotation 14403 14404Followed. 14405 14406@quotation 14407 14408"For stand-alone library-level objects of statically constrained 14409subtypes, the implementation should support all alignments 14410supported by the target linker. For example, page alignment is likely to 14411be supported for such objects, but not for subtypes." 14412@end quotation 14413 14414Followed. 14415 14416@geindex Size clauses 14417 14418@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 14419@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{226} 14420@section RM 13.3(42-43): Size Clauses 14421 14422 14423@quotation 14424 14425"The recommended level of support for the @code{Size} attribute of 14426objects is: 14427 14428A @code{Size} clause should be supported for an object if the specified 14429@code{Size} is at least as large as its subtype's @code{Size}, and 14430corresponds to a size in storage elements that is a multiple of the 14431object's @code{Alignment} (if the @code{Alignment} is nonzero)." 14432@end quotation 14433 14434Followed. 14435 14436@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 14437@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{227} 14438@section RM 13.3(50-56): Size Clauses 14439 14440 14441@quotation 14442 14443"If the @code{Size} of a subtype is specified, and allows for efficient 14444independent addressability (see 9.10) on the target architecture, then 14445the @code{Size} of the following objects of the subtype should equal the 14446@code{Size} of the subtype: 14447 14448Aliased objects (including components)." 14449@end quotation 14450 14451Followed. 14452 14453@quotation 14454 14455"@cite{Size} clause on a composite subtype should not affect the 14456internal layout of components." 14457@end quotation 14458 14459Followed. But note that this can be overridden by use of the implementation 14460pragma Implicit_Packing in the case of packed arrays. 14461 14462@quotation 14463 14464"The recommended level of support for the @code{Size} attribute of subtypes is: 14465 14466The @code{Size} (if not specified) of a static discrete or fixed point 14467subtype should be the number of bits needed to represent each value 14468belonging to the subtype using an unbiased representation, leaving space 14469for a sign bit only if the subtype contains negative values. If such a 14470subtype is a first subtype, then an implementation should support a 14471specified @code{Size} for it that reflects this representation." 14472@end quotation 14473 14474Followed. 14475 14476@quotation 14477 14478"For a subtype implemented with levels of indirection, the @code{Size} 14479should include the size of the pointers, but not the size of what they 14480point at." 14481@end quotation 14482 14483Followed. 14484 14485@geindex Component_Size clauses 14486 14487@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 14488@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{228} 14489@section RM 13.3(71-73): Component Size Clauses 14490 14491 14492@quotation 14493 14494"The recommended level of support for the @code{Component_Size} 14495attribute is: 14496 14497An implementation need not support specified @code{Component_Sizes} that are 14498less than the @code{Size} of the component subtype." 14499@end quotation 14500 14501Followed. 14502 14503@quotation 14504 14505"An implementation should support specified Component_Sizes that 14506are factors and multiples of the word size. For such 14507Component_Sizes, the array should contain no gaps between 14508components. For other Component_Sizes (if supported), the array 14509should contain no gaps between components when packing is also 14510specified; the implementation should forbid this combination in cases 14511where it cannot support a no-gaps representation." 14512@end quotation 14513 14514Followed. 14515 14516@geindex Enumeration representation clauses 14517 14518@geindex Representation clauses 14519@geindex enumeration 14520 14521@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 14522@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{229} 14523@section RM 13.4(9-10): Enumeration Representation Clauses 14524 14525 14526@quotation 14527 14528"The recommended level of support for enumeration representation clauses 14529is: 14530 14531An implementation need not support enumeration representation clauses 14532for boolean types, but should at minimum support the internal codes in 14533the range @code{System.Min_Int .. System.Max_Int}." 14534@end quotation 14535 14536Followed. 14537 14538@geindex Record representation clauses 14539 14540@geindex Representation clauses 14541@geindex records 14542 14543@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 14544@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{22a} 14545@section RM 13.5.1(17-22): Record Representation Clauses 14546 14547 14548@quotation 14549 14550"The recommended level of support for 14551@emph{record_representation_clause}s is: 14552 14553An implementation should support storage places that can be extracted 14554with a load, mask, shift sequence of machine code, and set with a load, 14555shift, mask, store sequence, given the available machine instructions 14556and run-time model." 14557@end quotation 14558 14559Followed. 14560 14561@quotation 14562 14563"A storage place should be supported if its size is equal to the 14564@code{Size} of the component subtype, and it starts and ends on a 14565boundary that obeys the @code{Alignment} of the component subtype." 14566@end quotation 14567 14568Followed. 14569 14570@quotation 14571 14572"If the default bit ordering applies to the declaration of a given type, 14573then for a component whose subtype's @code{Size} is less than the word 14574size, any storage place that does not cross an aligned word boundary 14575should be supported." 14576@end quotation 14577 14578Followed. 14579 14580@quotation 14581 14582"An implementation may reserve a storage place for the tag field of a 14583tagged type, and disallow other components from overlapping that place." 14584@end quotation 14585 14586Followed. The storage place for the tag field is the beginning of the tagged 14587record, and its size is Address'Size. GNAT will reject an explicit component 14588clause for the tag field. 14589 14590@quotation 14591 14592"An implementation need not support a @emph{component_clause} for a 14593component of an extension part if the storage place is not after the 14594storage places of all components of the parent type, whether or not 14595those storage places had been specified." 14596@end quotation 14597 14598Followed. The above advice on record representation clauses is followed, 14599and all mentioned features are implemented. 14600 14601@geindex Storage place attributes 14602 14603@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 14604@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{22b} 14605@section RM 13.5.2(5): Storage Place Attributes 14606 14607 14608@quotation 14609 14610"If a component is represented using some form of pointer (such as an 14611offset) to the actual data of the component, and this data is contiguous 14612with the rest of the object, then the storage place attributes should 14613reflect the place of the actual data, not the pointer. If a component is 14614allocated discontinuously from the rest of the object, then a warning 14615should be generated upon reference to one of its storage place 14616attributes." 14617@end quotation 14618 14619Followed. There are no such components in GNAT. 14620 14621@geindex Bit ordering 14622 14623@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 14624@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{22c} 14625@section RM 13.5.3(7-8): Bit Ordering 14626 14627 14628@quotation 14629 14630"The recommended level of support for the non-default bit ordering is: 14631 14632If @code{Word_Size} = @code{Storage_Unit}, then the implementation 14633should support the non-default bit ordering in addition to the default 14634bit ordering." 14635@end quotation 14636 14637Followed. Word size does not equal storage size in this implementation. 14638Thus non-default bit ordering is not supported. 14639 14640@geindex Address 14641@geindex as private type 14642 14643@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 14644@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{22d} 14645@section RM 13.7(37): Address as Private 14646 14647 14648@quotation 14649 14650"@cite{Address} should be of a private type." 14651@end quotation 14652 14653Followed. 14654 14655@geindex Operations 14656@geindex on `@w{`}Address`@w{`} 14657 14658@geindex Address 14659@geindex operations of 14660 14661@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14662@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{22e} 14663@section RM 13.7.1(16): Address Operations 14664 14665 14666@quotation 14667 14668"Operations in @code{System} and its children should reflect the target 14669environment semantics as closely as is reasonable. For example, on most 14670machines, it makes sense for address arithmetic to 'wrap around'. 14671Operations that do not make sense should raise @code{Program_Error}." 14672@end quotation 14673 14674Followed. Address arithmetic is modular arithmetic that wraps around. No 14675operation raises @code{Program_Error}, since all operations make sense. 14676 14677@geindex Unchecked conversion 14678 14679@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 14680@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{22f} 14681@section RM 13.9(14-17): Unchecked Conversion 14682 14683 14684@quotation 14685 14686"The @code{Size} of an array object should not include its bounds; hence, 14687the bounds should not be part of the converted data." 14688@end quotation 14689 14690Followed. 14691 14692@quotation 14693 14694"The implementation should not generate unnecessary run-time checks to 14695ensure that the representation of @code{S} is a representation of the 14696target type. It should take advantage of the permission to return by 14697reference when possible. Restrictions on unchecked conversions should be 14698avoided unless required by the target environment." 14699@end quotation 14700 14701Followed. There are no restrictions on unchecked conversion. A warning is 14702generated if the source and target types do not have the same size since 14703the semantics in this case may be target dependent. 14704 14705@quotation 14706 14707"The recommended level of support for unchecked conversions is: 14708 14709Unchecked conversions should be supported and should be reversible in 14710the cases where this clause defines the result. To enable meaningful use 14711of unchecked conversion, a contiguous representation should be used for 14712elementary subtypes, for statically constrained array subtypes whose 14713component subtype is one of the subtypes described in this paragraph, 14714and for record subtypes without discriminants whose component subtypes 14715are described in this paragraph." 14716@end quotation 14717 14718Followed. 14719 14720@geindex Heap usage 14721@geindex implicit 14722 14723@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 14724@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{230} 14725@section RM 13.11(23-25): Implicit Heap Usage 14726 14727 14728@quotation 14729 14730"An implementation should document any cases in which it dynamically 14731allocates heap storage for a purpose other than the evaluation of an 14732allocator." 14733@end quotation 14734 14735Followed, the only other points at which heap storage is dynamically 14736allocated are as follows: 14737 14738 14739@itemize * 14740 14741@item 14742At initial elaboration time, to allocate dynamically sized global 14743objects. 14744 14745@item 14746To allocate space for a task when a task is created. 14747 14748@item 14749To extend the secondary stack dynamically when needed. The secondary 14750stack is used for returning variable length results. 14751@end itemize 14752 14753 14754@quotation 14755 14756"A default (implementation-provided) storage pool for an 14757access-to-constant type should not have overhead to support deallocation of 14758individual objects." 14759@end quotation 14760 14761Followed. 14762 14763@quotation 14764 14765"A storage pool for an anonymous access type should be created at the 14766point of an allocator for the type, and be reclaimed when the designated 14767object becomes inaccessible." 14768@end quotation 14769 14770Followed. 14771 14772@geindex Unchecked deallocation 14773 14774@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 17 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice 14775@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{231} 14776@section RM 13.11.2(17): Unchecked Deallocation 14777 14778 14779@quotation 14780 14781"For a standard storage pool, @code{Free} should actually reclaim the 14782storage." 14783@end quotation 14784 14785Followed. 14786 14787@geindex Stream oriented attributes 14788 14789@node RM 13 13 2 17 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice 14790@anchor{gnat_rm/implementation_advice rm-13-13-2-17-stream-oriented-attributes}@anchor{232} 14791@section RM 13.13.2(17): Stream Oriented Attributes 14792 14793 14794@quotation 14795 14796"If a stream element is the same size as a storage element, then the 14797normal in-memory representation should be used by @code{Read} and 14798@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} 14799should use the smallest number of stream elements needed to represent 14800all values in the base range of the scalar type." 14801@end quotation 14802 14803Followed. By default, GNAT uses the interpretation suggested by AI-195, 14804which specifies using the size of the first subtype. 14805However, such an implementation is based on direct binary 14806representations and is therefore target- and endianness-dependent. 14807To address this issue, GNAT also supplies an alternate implementation 14808of the stream attributes @code{Read} and @code{Write}, 14809which uses the target-independent XDR standard representation 14810for scalar types. 14811 14812@geindex XDR representation 14813 14814@geindex Read attribute 14815 14816@geindex Write attribute 14817 14818@geindex Stream oriented attributes 14819 14820The XDR implementation is provided as an alternative body of the 14821@code{System.Stream_Attributes} package, in the file 14822@code{s-stratt-xdr.adb} in the GNAT library. 14823There is no @code{s-stratt-xdr.ads} file. 14824In order to install the XDR implementation, do the following: 14825 14826 14827@itemize * 14828 14829@item 14830Replace the default implementation of the 14831@code{System.Stream_Attributes} package with the XDR implementation. 14832For example on a Unix platform issue the commands: 14833 14834@example 14835$ mv s-stratt.adb s-stratt-default.adb 14836$ mv s-stratt-xdr.adb s-stratt.adb 14837@end example 14838 14839@item 14840Rebuild the GNAT run-time library as documented in 14841the @emph{GNAT and Libraries} section of the @cite{GNAT User's Guide}. 14842@end itemize 14843 14844@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 17 Stream Oriented Attributes,Implementation Advice 14845@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{233} 14846@section RM A.1(52): Names of Predefined Numeric Types 14847 14848 14849@quotation 14850 14851"If an implementation provides additional named predefined integer types, 14852then the names should end with @code{Integer} as in 14853@code{Long_Integer}. If an implementation provides additional named 14854predefined floating point types, then the names should end with 14855@code{Float} as in @code{Long_Float}." 14856@end quotation 14857 14858Followed. 14859 14860@geindex Ada.Characters.Handling 14861 14862@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 14863@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{234} 14864@section RM A.3.2(49): @code{Ada.Characters.Handling} 14865 14866 14867@quotation 14868 14869"If an implementation provides a localized definition of @code{Character} 14870or @code{Wide_Character}, then the effects of the subprograms in 14871@code{Characters.Handling} should reflect the localizations. 14872See also 3.5.2." 14873@end quotation 14874 14875Followed. GNAT provides no such localized definitions. 14876 14877@geindex Bounded-length strings 14878 14879@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 14880@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{235} 14881@section RM A.4.4(106): Bounded-Length String Handling 14882 14883 14884@quotation 14885 14886"Bounded string objects should not be implemented by implicit pointers 14887and dynamic allocation." 14888@end quotation 14889 14890Followed. No implicit pointers or dynamic allocation are used. 14891 14892@geindex Random number generation 14893 14894@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 14895@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{236} 14896@section RM A.5.2(46-47): Random Number Generation 14897 14898 14899@quotation 14900 14901"Any storage associated with an object of type @code{Generator} should be 14902reclaimed on exit from the scope of the object." 14903@end quotation 14904 14905Followed. 14906 14907@quotation 14908 14909"If the generator period is sufficiently long in relation to the number 14910of distinct initiator values, then each possible value of 14911@code{Initiator} passed to @code{Reset} should initiate a sequence of 14912random numbers that does not, in a practical sense, overlap the sequence 14913initiated by any other value. If this is not possible, then the mapping 14914between initiator values and generator states should be a rapidly 14915varying function of the initiator value." 14916@end quotation 14917 14918Followed. The generator period is sufficiently long for the first 14919condition here to hold true. 14920 14921@geindex Get_Immediate 14922 14923@node RM A 10 7 23 Get_Immediate,RM B 1 39-41 Pragma Export,RM A 5 2 46-47 Random Number Generation,Implementation Advice 14924@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{237} 14925@section RM A.10.7(23): @code{Get_Immediate} 14926 14927 14928@quotation 14929 14930"The @code{Get_Immediate} procedures should be implemented with 14931unbuffered input. For a device such as a keyboard, input should be 14932available if a key has already been typed, whereas for a disk 14933file, input should always be available except at end of file. For a file 14934associated with a keyboard-like device, any line-editing features of the 14935underlying operating system should be disabled during the execution of 14936@code{Get_Immediate}." 14937@end quotation 14938 14939Followed on all targets except VxWorks. For VxWorks, there is no way to 14940provide this functionality that does not result in the input buffer being 14941flushed before the @code{Get_Immediate} call. A special unit 14942@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 14943this functionality. 14944 14945@geindex Export 14946 14947@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice 14948@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{238} 14949@section RM B.1(39-41): Pragma @code{Export} 14950 14951 14952@quotation 14953 14954"If an implementation supports pragma @code{Export} to a given language, 14955then it should also allow the main subprogram to be written in that 14956language. It should support some mechanism for invoking the elaboration 14957of the Ada library units included in the system, and for invoking the 14958finalization of the environment task. On typical systems, the 14959recommended mechanism is to provide two subprograms whose link names are 14960@code{adainit} and @code{adafinal}. @code{adainit} should contain the 14961elaboration code for library units. @code{adafinal} should contain the 14962finalization code. These subprograms should have no effect the second 14963and subsequent time they are called." 14964@end quotation 14965 14966Followed. 14967 14968@quotation 14969 14970"Automatic elaboration of pre-elaborated packages should be 14971provided when pragma @code{Export} is supported." 14972@end quotation 14973 14974Followed when the main program is in Ada. If the main program is in a 14975foreign language, then 14976@code{adainit} must be called to elaborate pre-elaborated 14977packages. 14978 14979@quotation 14980 14981"For each supported convention @emph{L} other than @code{Intrinsic}, an 14982implementation should support @code{Import} and @code{Export} pragmas 14983for objects of @emph{L}-compatible types and for subprograms, and pragma 14984@cite{Convention} for @emph{L}-eligible types and for subprograms, 14985presuming the other language has corresponding features. Pragma 14986@code{Convention} need not be supported for scalar types." 14987@end quotation 14988 14989Followed. 14990 14991@geindex Package Interfaces 14992 14993@geindex Interfaces 14994 14995@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 14996@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{239} 14997@section RM B.2(12-13): Package @code{Interfaces} 14998 14999 15000@quotation 15001 15002"For each implementation-defined convention identifier, there should be a 15003child package of package Interfaces with the corresponding name. This 15004package should contain any declarations that would be useful for 15005interfacing to the language (implementation) represented by the 15006convention. Any declarations useful for interfacing to any language on 15007the given hardware architecture should be provided directly in 15008@code{Interfaces}." 15009@end quotation 15010 15011Followed. 15012 15013@quotation 15014 15015"An implementation supporting an interface to C, COBOL, or Fortran should 15016provide the corresponding package or packages described in the following 15017clauses." 15018@end quotation 15019 15020Followed. GNAT provides all the packages described in this section. 15021 15022@geindex C 15023@geindex interfacing with 15024 15025@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 15026@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{23a} 15027@section RM B.3(63-71): Interfacing with C 15028 15029 15030@quotation 15031 15032"An implementation should support the following interface correspondences 15033between Ada and C." 15034@end quotation 15035 15036Followed. 15037 15038@quotation 15039 15040"An Ada procedure corresponds to a void-returning C function." 15041@end quotation 15042 15043Followed. 15044 15045@quotation 15046 15047"An Ada function corresponds to a non-void C function." 15048@end quotation 15049 15050Followed. 15051 15052@quotation 15053 15054"An Ada @code{in} scalar parameter is passed as a scalar argument to a C 15055function." 15056@end quotation 15057 15058Followed. 15059 15060@quotation 15061 15062"An Ada @code{in} parameter of an access-to-object type with designated 15063type @code{T} is passed as a @code{t*} argument to a C function, 15064where @code{t} is the C type corresponding to the Ada type @code{T}." 15065@end quotation 15066 15067Followed. 15068 15069@quotation 15070 15071"An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} 15072parameter of an elementary type @code{T}, is passed as a @code{t*} 15073argument to a C function, where @code{t} is the C type corresponding to 15074the Ada type @code{T}. In the case of an elementary @code{out} or 15075@code{in out} parameter, a pointer to a temporary copy is used to 15076preserve by-copy semantics." 15077@end quotation 15078 15079Followed. 15080 15081@quotation 15082 15083"An Ada parameter of a record type @code{T}, of any mode, is passed as a 15084@code{t*} argument to a C function, where @code{t} is the C 15085structure corresponding to the Ada type @code{T}." 15086@end quotation 15087 15088Followed. This convention may be overridden by the use of the C_Pass_By_Copy 15089pragma, or Convention, or by explicitly specifying the mechanism for a given 15090call using an extended import or export pragma. 15091 15092@quotation 15093 15094"An Ada parameter of an array type with component type @code{T}, of any 15095mode, is passed as a @code{t*} argument to a C function, where 15096@code{t} is the C type corresponding to the Ada type @code{T}." 15097@end quotation 15098 15099Followed. 15100 15101@quotation 15102 15103"An Ada parameter of an access-to-subprogram type is passed as a pointer 15104to a C function whose prototype corresponds to the designated 15105subprogram's specification." 15106@end quotation 15107 15108Followed. 15109 15110@geindex COBOL 15111@geindex interfacing with 15112 15113@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 15114@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{23b} 15115@section RM B.4(95-98): Interfacing with COBOL 15116 15117 15118@quotation 15119 15120"An Ada implementation should support the following interface 15121correspondences between Ada and COBOL." 15122@end quotation 15123 15124Followed. 15125 15126@quotation 15127 15128"An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of 15129the COBOL type corresponding to @code{T}." 15130@end quotation 15131 15132Followed. 15133 15134@quotation 15135 15136"An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 15137the corresponding COBOL type." 15138@end quotation 15139 15140Followed. 15141 15142@quotation 15143 15144"Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 15145COBOL type corresponding to the Ada parameter type; for scalars, a local 15146copy is used if necessary to ensure by-copy semantics." 15147@end quotation 15148 15149Followed. 15150 15151@geindex Fortran 15152@geindex interfacing with 15153 15154@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 15155@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{23c} 15156@section RM B.5(22-26): Interfacing with Fortran 15157 15158 15159@quotation 15160 15161"An Ada implementation should support the following interface 15162correspondences between Ada and Fortran:" 15163@end quotation 15164 15165Followed. 15166 15167@quotation 15168 15169"An Ada procedure corresponds to a Fortran subroutine." 15170@end quotation 15171 15172Followed. 15173 15174@quotation 15175 15176"An Ada function corresponds to a Fortran function." 15177@end quotation 15178 15179Followed. 15180 15181@quotation 15182 15183"An Ada parameter of an elementary, array, or record type @code{T} is 15184passed as a @code{T} argument to a Fortran procedure, where @code{T} is 15185the Fortran type corresponding to the Ada type @code{T}, and where the 15186INTENT attribute of the corresponding dummy argument matches the Ada 15187formal parameter mode; the Fortran implementation's parameter passing 15188conventions are used. For elementary types, a local copy is used if 15189necessary to ensure by-copy semantics." 15190@end quotation 15191 15192Followed. 15193 15194@quotation 15195 15196"An Ada parameter of an access-to-subprogram type is passed as a 15197reference to a Fortran procedure whose interface corresponds to the 15198designated subprogram's specification." 15199@end quotation 15200 15201Followed. 15202 15203@geindex Machine operations 15204 15205@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 15206@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{23d} 15207@section RM C.1(3-5): Access to Machine Operations 15208 15209 15210@quotation 15211 15212"The machine code or intrinsic support should allow access to all 15213operations normally available to assembly language programmers for the 15214target environment, including privileged instructions, if any." 15215@end quotation 15216 15217Followed. 15218 15219@quotation 15220 15221"The interfacing pragmas (see Annex B) should support interface to 15222assembler; the default assembler should be associated with the 15223convention identifier @code{Assembler}." 15224@end quotation 15225 15226Followed. 15227 15228@quotation 15229 15230"If an entity is exported to assembly language, then the implementation 15231should allocate it at an addressable location, and should ensure that it 15232is retained by the linking process, even if not otherwise referenced 15233from the Ada code. The implementation should assume that any call to a 15234machine code or assembler subprogram is allowed to read or update every 15235object that is specified as exported." 15236@end quotation 15237 15238Followed. 15239 15240@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 15241@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{23e} 15242@section RM C.1(10-16): Access to Machine Operations 15243 15244 15245@quotation 15246 15247"The implementation should ensure that little or no overhead is 15248associated with calling intrinsic and machine-code subprograms." 15249@end quotation 15250 15251Followed for both intrinsics and machine-code subprograms. 15252 15253@quotation 15254 15255"It is recommended that intrinsic subprograms be provided for convenient 15256access to any machine operations that provide special capabilities or 15257efficiency and that are not otherwise available through the language 15258constructs." 15259@end quotation 15260 15261Followed. A full set of machine operation intrinsic subprograms is provided. 15262 15263@quotation 15264 15265"Atomic read-modify-write operations---e.g., test and set, compare and 15266swap, decrement and test, enqueue/dequeue." 15267@end quotation 15268 15269Followed on any target supporting such operations. 15270 15271@quotation 15272 15273"Standard numeric functions---e.g.:, sin, log." 15274@end quotation 15275 15276Followed on any target supporting such operations. 15277 15278@quotation 15279 15280"String manipulation operations---e.g.:, translate and test." 15281@end quotation 15282 15283Followed on any target supporting such operations. 15284 15285@quotation 15286 15287"Vector operations---e.g.:, compare vector against thresholds." 15288@end quotation 15289 15290Followed on any target supporting such operations. 15291 15292@quotation 15293 15294"Direct operations on I/O ports." 15295@end quotation 15296 15297Followed on any target supporting such operations. 15298 15299@geindex Interrupt support 15300 15301@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 15302@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{23f} 15303@section RM C.3(28): Interrupt Support 15304 15305 15306@quotation 15307 15308"If the @code{Ceiling_Locking} policy is not in effect, the 15309implementation should provide means for the application to specify which 15310interrupts are to be blocked during protected actions, if the underlying 15311system allows for a finer-grain control of interrupt blocking." 15312@end quotation 15313 15314Followed. The underlying system does not allow for finer-grain control 15315of interrupt blocking. 15316 15317@geindex Protected procedure handlers 15318 15319@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 15320@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{240} 15321@section RM C.3.1(20-21): Protected Procedure Handlers 15322 15323 15324@quotation 15325 15326"Whenever possible, the implementation should allow interrupt handlers to 15327be called directly by the hardware." 15328@end quotation 15329 15330Followed on any target where the underlying operating system permits 15331such direct calls. 15332 15333@quotation 15334 15335"Whenever practical, violations of any 15336implementation-defined restrictions should be detected before run time." 15337@end quotation 15338 15339Followed. Compile time warnings are given when possible. 15340 15341@geindex Package `@w{`}Interrupts`@w{`} 15342 15343@geindex Interrupts 15344 15345@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 15346@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{241} 15347@section RM C.3.2(25): Package @code{Interrupts} 15348 15349 15350@quotation 15351 15352"If implementation-defined forms of interrupt handler procedures are 15353supported, such as protected procedures with parameters, then for each 15354such form of a handler, a type analogous to @code{Parameterless_Handler} 15355should be specified in a child package of @code{Interrupts}, with the 15356same operations as in the predefined package Interrupts." 15357@end quotation 15358 15359Followed. 15360 15361@geindex Pre-elaboration requirements 15362 15363@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 15364@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{242} 15365@section RM C.4(14): Pre-elaboration Requirements 15366 15367 15368@quotation 15369 15370"It is recommended that pre-elaborated packages be implemented in such a 15371way that there should be little or no code executed at run time for the 15372elaboration of entities not already covered by the Implementation 15373Requirements." 15374@end quotation 15375 15376Followed. Executable code is generated in some cases, e.g., loops 15377to initialize large arrays. 15378 15379@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 15380@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{243} 15381@section RM C.5(8): Pragma @code{Discard_Names} 15382 15383 15384@quotation 15385 15386"If the pragma applies to an entity, then the implementation should 15387reduce the amount of storage used for storing names associated with that 15388entity." 15389@end quotation 15390 15391Followed. 15392 15393@geindex Package Task_Attributes 15394 15395@geindex Task_Attributes 15396 15397@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 15398@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{244} 15399@section RM C.7.2(30): The Package Task_Attributes 15400 15401 15402@quotation 15403 15404"Some implementations are targeted to domains in which memory use at run 15405time must be completely deterministic. For such implementations, it is 15406recommended that the storage for task attributes will be pre-allocated 15407statically and not from the heap. This can be accomplished by either 15408placing restrictions on the number and the size of the task's 15409attributes, or by using the pre-allocated storage for the first @code{N} 15410attribute objects, and the heap for the others. In the latter case, 15411@code{N} should be documented." 15412@end quotation 15413 15414Not followed. This implementation is not targeted to such a domain. 15415 15416@geindex Locking Policies 15417 15418@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 15419@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{245} 15420@section RM D.3(17): Locking Policies 15421 15422 15423@quotation 15424 15425"The implementation should use names that end with @code{_Locking} for 15426locking policies defined by the implementation." 15427@end quotation 15428 15429Followed. Two implementation-defined locking policies are defined, 15430whose names (@code{Inheritance_Locking} and 15431@code{Concurrent_Readers_Locking}) follow this suggestion. 15432 15433@geindex Entry queuing policies 15434 15435@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 15436@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{246} 15437@section RM D.4(16): Entry Queuing Policies 15438 15439 15440@quotation 15441 15442"Names that end with @code{_Queuing} should be used 15443for all implementation-defined queuing policies." 15444@end quotation 15445 15446Followed. No such implementation-defined queuing policies exist. 15447 15448@geindex Preemptive abort 15449 15450@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 15451@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{247} 15452@section RM D.6(9-10): Preemptive Abort 15453 15454 15455@quotation 15456 15457"Even though the @emph{abort_statement} is included in the list of 15458potentially blocking operations (see 9.5.1), it is recommended that this 15459statement be implemented in a way that never requires the task executing 15460the @emph{abort_statement} to block." 15461@end quotation 15462 15463Followed. 15464 15465@quotation 15466 15467"On a multi-processor, the delay associated with aborting a task on 15468another processor should be bounded; the implementation should use 15469periodic polling, if necessary, to achieve this." 15470@end quotation 15471 15472Followed. 15473 15474@geindex Tasking restrictions 15475 15476@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 15477@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{248} 15478@section RM D.7(21): Tasking Restrictions 15479 15480 15481@quotation 15482 15483"When feasible, the implementation should take advantage of the specified 15484restrictions to produce a more efficient implementation." 15485@end quotation 15486 15487GNAT currently takes advantage of these restrictions by providing an optimized 15488run time when the Ravenscar profile and the GNAT restricted run time set 15489of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 15490pragma @code{Profile (Restricted)} for more details. 15491 15492@geindex Time 15493@geindex monotonic 15494 15495@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 15496@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{249} 15497@section RM D.8(47-49): Monotonic Time 15498 15499 15500@quotation 15501 15502"When appropriate, implementations should provide configuration 15503mechanisms to change the value of @code{Tick}." 15504@end quotation 15505 15506Such configuration mechanisms are not appropriate to this implementation 15507and are thus not supported. 15508 15509@quotation 15510 15511"It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 15512be implemented as transformations of the same time base." 15513@end quotation 15514 15515Followed. 15516 15517@quotation 15518 15519"It is recommended that the best time base which exists in 15520the underlying system be available to the application through 15521@code{Clock}. @cite{Best} may mean highest accuracy or largest range." 15522@end quotation 15523 15524Followed. 15525 15526@geindex Partition communication subsystem 15527 15528@geindex PCS 15529 15530@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 15531@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{24a} 15532@section RM E.5(28-29): Partition Communication Subsystem 15533 15534 15535@quotation 15536 15537"Whenever possible, the PCS on the called partition should allow for 15538multiple tasks to call the RPC-receiver with different messages and 15539should allow them to block until the corresponding subprogram body 15540returns." 15541@end quotation 15542 15543Followed by GLADE, a separately supplied PCS that can be used with 15544GNAT. 15545 15546@quotation 15547 15548"The @code{Write} operation on a stream of type @code{Params_Stream_Type} 15549should raise @code{Storage_Error} if it runs out of space trying to 15550write the @code{Item} into the stream." 15551@end quotation 15552 15553Followed by GLADE, a separately supplied PCS that can be used with 15554GNAT. 15555 15556@geindex COBOL support 15557 15558@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 15559@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{24b} 15560@section RM F(7): COBOL Support 15561 15562 15563@quotation 15564 15565"If COBOL (respectively, C) is widely supported in the target 15566environment, implementations supporting the Information Systems Annex 15567should provide the child package @code{Interfaces.COBOL} (respectively, 15568@code{Interfaces.C}) specified in Annex B and should support a 15569@code{convention_identifier} of COBOL (respectively, C) in the interfacing 15570pragmas (see Annex B), thus allowing Ada programs to interface with 15571programs written in that language." 15572@end quotation 15573 15574Followed. 15575 15576@geindex Decimal radix support 15577 15578@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 15579@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{24c} 15580@section RM F.1(2): Decimal Radix Support 15581 15582 15583@quotation 15584 15585"Packed decimal should be used as the internal representation for objects 15586of subtype @code{S} when @code{S}'Machine_Radix = 10." 15587@end quotation 15588 15589Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary 15590representations. 15591 15592@geindex Numerics 15593 15594@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 15595@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{24d} 15596@section RM G: Numerics 15597 15598 15599@quotation 15600 15601"If Fortran (respectively, C) is widely supported in the target 15602environment, implementations supporting the Numerics Annex 15603should provide the child package @code{Interfaces.Fortran} (respectively, 15604@code{Interfaces.C}) specified in Annex B and should support a 15605@code{convention_identifier} of Fortran (respectively, C) in the interfacing 15606pragmas (see Annex B), thus allowing Ada programs to interface with 15607programs written in that language." 15608@end quotation 15609 15610Followed. 15611 15612@geindex Complex types 15613 15614@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15615@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{24e} 15616@section RM G.1.1(56-58): Complex Types 15617 15618 15619@quotation 15620 15621"Because the usual mathematical meaning of multiplication of a complex 15622operand and a real operand is that of the scaling of both components of 15623the former by the latter, an implementation should not perform this 15624operation by first promoting the real operand to complex type and then 15625performing a full complex multiplication. In systems that, in the 15626future, support an Ada binding to IEC 559:1989, the latter technique 15627will not generate the required result when one of the components of the 15628complex operand is infinite. (Explicit multiplication of the infinite 15629component by the zero component obtained during promotion yields a NaN 15630that propagates into the final result.) Analogous advice applies in the 15631case of multiplication of a complex operand and a pure-imaginary 15632operand, and in the case of division of a complex operand by a real or 15633pure-imaginary operand." 15634@end quotation 15635 15636Not followed. 15637 15638@quotation 15639 15640"Similarly, because the usual mathematical meaning of addition of a 15641complex operand and a real operand is that the imaginary operand remains 15642unchanged, an implementation should not perform this operation by first 15643promoting the real operand to complex type and then performing a full 15644complex addition. In implementations in which the @code{Signed_Zeros} 15645attribute of the component type is @code{True} (and which therefore 15646conform to IEC 559:1989 in regard to the handling of the sign of zero in 15647predefined arithmetic operations), the latter technique will not 15648generate the required result when the imaginary component of the complex 15649operand is a negatively signed zero. (Explicit addition of the negative 15650zero to the zero obtained during promotion yields a positive zero.) 15651Analogous advice applies in the case of addition of a complex operand 15652and a pure-imaginary operand, and in the case of subtraction of a 15653complex operand and a real or pure-imaginary operand." 15654@end quotation 15655 15656Not followed. 15657 15658@quotation 15659 15660"Implementations in which @code{Real'Signed_Zeros} is @code{True} should 15661attempt to provide a rational treatment of the signs of zero results and 15662result components. As one example, the result of the @code{Argument} 15663function should have the sign of the imaginary component of the 15664parameter @code{X} when the point represented by that parameter lies on 15665the positive real axis; as another, the sign of the imaginary component 15666of the @code{Compose_From_Polar} function should be the same as 15667(respectively, the opposite of) that of the @code{Argument} parameter when that 15668parameter has a value of zero and the @code{Modulus} parameter has a 15669nonnegative (respectively, negative) value." 15670@end quotation 15671 15672Followed. 15673 15674@geindex Complex elementary functions 15675 15676@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 15677@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{24f} 15678@section RM G.1.2(49): Complex Elementary Functions 15679 15680 15681@quotation 15682 15683"Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 15684@code{True} should attempt to provide a rational treatment of the signs 15685of zero results and result components. For example, many of the complex 15686elementary functions have components that are odd functions of one of 15687the parameter components; in these cases, the result component should 15688have the sign of the parameter component at the origin. Other complex 15689elementary functions have zero components whose sign is opposite that of 15690a parameter component at the origin, or is always positive or always 15691negative." 15692@end quotation 15693 15694Followed. 15695 15696@geindex Accuracy requirements 15697 15698@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 15699@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{250} 15700@section RM G.2.4(19): Accuracy Requirements 15701 15702 15703@quotation 15704 15705"The versions of the forward trigonometric functions without a 15706@code{Cycle} parameter should not be implemented by calling the 15707corresponding version with a @code{Cycle} parameter of 15708@code{2.0*Numerics.Pi}, since this will not provide the required 15709accuracy in some portions of the domain. For the same reason, the 15710version of @code{Log} without a @code{Base} parameter should not be 15711implemented by calling the corresponding version with a @code{Base} 15712parameter of @code{Numerics.e}." 15713@end quotation 15714 15715Followed. 15716 15717@geindex Complex arithmetic accuracy 15718 15719@geindex Accuracy 15720@geindex complex arithmetic 15721 15722@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 15723@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{251} 15724@section RM G.2.6(15): Complex Arithmetic Accuracy 15725 15726 15727@quotation 15728 15729"The version of the @code{Compose_From_Polar} function without a 15730@code{Cycle} parameter should not be implemented by calling the 15731corresponding version with a @code{Cycle} parameter of 15732@code{2.0*Numerics.Pi}, since this will not provide the required 15733accuracy in some portions of the domain." 15734@end quotation 15735 15736Followed. 15737 15738@geindex Sequential elaboration policy 15739 15740@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15741@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{252} 15742@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15743 15744 15745@quotation 15746 15747"If the partition elaboration policy is @code{Sequential} and the 15748Environment task becomes permanently blocked during elaboration then the 15749partition is deadlocked and it is recommended that the partition be 15750immediately terminated." 15751@end quotation 15752 15753Not followed. 15754 15755@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15756@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{253}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{254} 15757@chapter Implementation Defined Characteristics 15758 15759 15760In addition to the implementation dependent pragmas and attributes, and the 15761implementation advice, there are a number of other Ada features that are 15762potentially implementation dependent and are designated as 15763implementation-defined. These are mentioned throughout the Ada Reference 15764Manual, and are summarized in Annex M. 15765 15766A requirement for conforming Ada compilers is that they provide 15767documentation describing how the implementation deals with each of these 15768issues. In this chapter you will find each point in Annex M listed, 15769followed by a description of how GNAT 15770handles the implementation dependence. 15771 15772You can use this chapter as a guide to minimizing implementation 15773dependent features in your programs if portability to other compilers 15774and other operating systems is an important consideration. The numbers 15775in each entry below correspond to the paragraph numbers in the Ada 15776Reference Manual. 15777 15778 15779@itemize * 15780 15781@item 15782"Whether or not each recommendation given in Implementation 15783Advice is followed. See 1.1.2(37)." 15784@end itemize 15785 15786See @ref{a,,Implementation Advice}. 15787 15788 15789@itemize * 15790 15791@item 15792"Capacity limitations of the implementation. See 1.1.3(3)." 15793@end itemize 15794 15795The complexity of programs that can be processed is limited only by the 15796total amount of available virtual memory, and disk space for the 15797generated object files. 15798 15799 15800@itemize * 15801 15802@item 15803"Variations from the standard that are impractical to avoid 15804given the implementation's execution environment. See 1.1.3(6)." 15805@end itemize 15806 15807There are no variations from the standard. 15808 15809 15810@itemize * 15811 15812@item 15813"Which code_statements cause external 15814interactions. See 1.1.3(10)." 15815@end itemize 15816 15817Any @emph{code_statement} can potentially cause external interactions. 15818 15819 15820@itemize * 15821 15822@item 15823"The coded representation for the text of an Ada 15824program. See 2.1(4)." 15825@end itemize 15826 15827See separate section on source representation. 15828 15829 15830@itemize * 15831 15832@item 15833"The control functions allowed in comments. See 2.1(14)." 15834@end itemize 15835 15836See separate section on source representation. 15837 15838 15839@itemize * 15840 15841@item 15842"The representation for an end of line. See 2.2(2)." 15843@end itemize 15844 15845See separate section on source representation. 15846 15847 15848@itemize * 15849 15850@item 15851"Maximum supported line length and lexical element 15852length. See 2.2(15)." 15853@end itemize 15854 15855The maximum line length is 255 characters and the maximum length of 15856a lexical element is also 255 characters. This is the default setting 15857if not overridden by the use of compiler switch @emph{-gnaty} (which 15858sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15859line length to be specified to be any value up to 32767. The maximum 15860length of a lexical element is the same as the maximum line length. 15861 15862 15863@itemize * 15864 15865@item 15866"Implementation defined pragmas. See 2.8(14)." 15867@end itemize 15868 15869See @ref{7,,Implementation Defined Pragmas}. 15870 15871 15872@itemize * 15873 15874@item 15875"Effect of pragma @code{Optimize}. See 2.8(27)." 15876@end itemize 15877 15878Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 15879parameter, checks that the optimization flag is set, and aborts if it is 15880not. 15881 15882 15883@itemize * 15884 15885@item 15886"The sequence of characters of the value returned by 15887@code{S'Image} when some of the graphic characters of 15888@code{S'Wide_Image} are not defined in @code{Character}. See 158893.5(37)." 15890@end itemize 15891 15892The sequence of characters is as defined by the wide character encoding 15893method used for the source. See section on source representation for 15894further details. 15895 15896 15897@itemize * 15898 15899@item 15900"The predefined integer types declared in 15901@code{Standard}. See 3.5.4(25)." 15902@end itemize 15903 15904 15905@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15906@headitem 15907 15908Type 15909 15910@tab 15911 15912Representation 15913 15914@item 15915 15916@emph{Short_Short_Integer} 15917 15918@tab 15919 159208 bit signed 15921 15922@item 15923 15924@emph{Short_Integer} 15925 15926@tab 15927 15928(Short) 16 bit signed 15929 15930@item 15931 15932@emph{Integer} 15933 15934@tab 15935 1593632 bit signed 15937 15938@item 15939 15940@emph{Long_Integer} 15941 15942@tab 15943 1594464 bit signed (on most 64 bit targets, 15945depending on the C definition of long). 1594632 bit signed (all other targets) 15947 15948@item 15949 15950@emph{Long_Long_Integer} 15951 15952@tab 15953 1595464 bit signed 15955 15956@end multitable 15957 15958 15959 15960@itemize * 15961 15962@item 15963"Any nonstandard integer types and the operators defined 15964for them. See 3.5.4(26)." 15965@end itemize 15966 15967There are no nonstandard integer types. 15968 15969 15970@itemize * 15971 15972@item 15973"Any nonstandard real types and the operators defined for 15974them. See 3.5.6(8)." 15975@end itemize 15976 15977There are no nonstandard real types. 15978 15979 15980@itemize * 15981 15982@item 15983"What combinations of requested decimal precision and range 15984are supported for floating point types. See 3.5.7(7)." 15985@end itemize 15986 15987The precision and range is as defined by the IEEE standard. 15988 15989 15990@itemize * 15991 15992@item 15993"The predefined floating point types declared in 15994@code{Standard}. See 3.5.7(16)." 15995@end itemize 15996 15997 15998@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15999@headitem 16000 16001Type 16002 16003@tab 16004 16005Representation 16006 16007@item 16008 16009@emph{Short_Float} 16010 16011@tab 16012 1601332 bit IEEE short 16014 16015@item 16016 16017@emph{Float} 16018 16019@tab 16020 16021(Short) 32 bit IEEE short 16022 16023@item 16024 16025@emph{Long_Float} 16026 16027@tab 16028 1602964 bit IEEE long 16030 16031@item 16032 16033@emph{Long_Long_Float} 16034 16035@tab 16036 1603764 bit IEEE long (80 bit IEEE long on x86 processors) 16038 16039@end multitable 16040 16041 16042 16043@itemize * 16044 16045@item 16046"The small of an ordinary fixed point type. See 3.5.9(8)." 16047@end itemize 16048 16049@code{Fine_Delta} is 2**(-63) 16050 16051 16052@itemize * 16053 16054@item 16055"What combinations of small, range, and digits are 16056supported for fixed point types. See 3.5.9(10)." 16057@end itemize 16058 16059Any combinations are permitted that do not result in a small less than 16060@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 16061If the mantissa is larger than 53 bits on machines where Long_Long_Float 16062is 64 bits (true of all architectures except ia32), then the output from 16063Text_IO is accurate to only 53 bits, rather than the full mantissa. This 16064is because floating-point conversions are used to convert fixed point. 16065 16066 16067@itemize * 16068 16069@item 16070"The result of @code{Tags.Expanded_Name} for types declared 16071within an unnamed @emph{block_statement}. See 3.9(10)." 16072@end itemize 16073 16074Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a 16075decimal integer are allocated. 16076 16077 16078@itemize * 16079 16080@item 16081"Implementation-defined attributes. See 4.1.4(12)." 16082@end itemize 16083 16084See @ref{8,,Implementation Defined Attributes}. 16085 16086 16087@itemize * 16088 16089@item 16090"Any implementation-defined time types. See 9.6(6)." 16091@end itemize 16092 16093There are no implementation-defined time types. 16094 16095 16096@itemize * 16097 16098@item 16099"The time base associated with relative delays." 16100@end itemize 16101 16102See 9.6(20). The time base used is that provided by the C library 16103function @code{gettimeofday}. 16104 16105 16106@itemize * 16107 16108@item 16109"The time base of the type @code{Calendar.Time}. See 161109.6(23)." 16111@end itemize 16112 16113The time base used is that provided by the C library function 16114@code{gettimeofday}. 16115 16116 16117@itemize * 16118 16119@item 16120"The time zone used for package @code{Calendar} 16121operations. See 9.6(24)." 16122@end itemize 16123 16124The time zone used by package @code{Calendar} is the current system time zone 16125setting for local time, as accessed by the C library function 16126@code{localtime}. 16127 16128 16129@itemize * 16130 16131@item 16132"Any limit on @emph{delay_until_statements} of 16133@emph{select_statements}. See 9.6(29)." 16134@end itemize 16135 16136There are no such limits. 16137 16138 16139@itemize * 16140 16141@item 16142"Whether or not two non-overlapping parts of a composite 16143object are independently addressable, in the case where packing, record 16144layout, or @code{Component_Size} is specified for the object. See 161459.10(1)." 16146@end itemize 16147 16148Separate components are independently addressable if they do not share 16149overlapping storage units. 16150 16151 16152@itemize * 16153 16154@item 16155"The representation for a compilation. See 10.1(2)." 16156@end itemize 16157 16158A compilation is represented by a sequence of files presented to the 16159compiler in a single invocation of the @emph{gcc} command. 16160 16161 16162@itemize * 16163 16164@item 16165"Any restrictions on compilations that contain multiple 16166compilation_units. See 10.1(4)." 16167@end itemize 16168 16169No single file can contain more than one compilation unit, but any 16170sequence of files can be presented to the compiler as a single 16171compilation. 16172 16173 16174@itemize * 16175 16176@item 16177"The mechanisms for creating an environment and for adding 16178and replacing compilation units. See 10.1.4(3)." 16179@end itemize 16180 16181See separate section on compilation model. 16182 16183 16184@itemize * 16185 16186@item 16187"The manner of explicitly assigning library units to a 16188partition. See 10.2(2)." 16189@end itemize 16190 16191If a unit contains an Ada main program, then the Ada units for the partition 16192are determined by recursive application of the rules in the Ada Reference 16193Manual section 10.2(2-6). In other words, the Ada units will be those that 16194are needed by the main program, and then this definition of need is applied 16195recursively to those units, and the partition contains the transitive 16196closure determined by this relationship. In short, all the necessary units 16197are included, with no need to explicitly specify the list. If additional 16198units are required, e.g., by foreign language units, then all units must be 16199mentioned in the context clause of one of the needed Ada units. 16200 16201If the partition contains no main program, or if the main program is in 16202a language other than Ada, then GNAT 16203provides the binder options @emph{-z} and @emph{-n} respectively, and in 16204this case a list of units can be explicitly supplied to the binder for 16205inclusion in the partition (all units needed by these units will also 16206be included automatically). For full details on the use of these 16207options, refer to @emph{GNAT Make Program gnatmake} in the 16208@cite{GNAT User's Guide}. 16209 16210 16211@itemize * 16212 16213@item 16214"The implementation-defined means, if any, of specifying 16215which compilation units are needed by a given compilation unit. See 1621610.2(2)." 16217@end itemize 16218 16219The units needed by a given compilation unit are as defined in 16220the Ada Reference Manual section 10.2(2-6). There are no 16221implementation-defined pragmas or other implementation-defined 16222means for specifying needed units. 16223 16224 16225@itemize * 16226 16227@item 16228"The manner of designating the main subprogram of a 16229partition. See 10.2(7)." 16230@end itemize 16231 16232The main program is designated by providing the name of the 16233corresponding @code{ALI} file as the input parameter to the binder. 16234 16235 16236@itemize * 16237 16238@item 16239"The order of elaboration of @emph{library_items}. See 1624010.2(18)." 16241@end itemize 16242 16243The first constraint on ordering is that it meets the requirements of 16244Chapter 10 of the Ada Reference Manual. This still leaves some 16245implementation dependent choices, which are resolved by first 16246elaborating bodies as early as possible (i.e., in preference to specs 16247where there is a choice), and second by evaluating the immediate with 16248clauses of a unit to determine the probably best choice, and 16249third by elaborating in alphabetical order of unit names 16250where a choice still remains. 16251 16252 16253@itemize * 16254 16255@item 16256"Parameter passing and function return for the main 16257subprogram. See 10.2(21)." 16258@end itemize 16259 16260The main program has no parameters. It may be a procedure, or a function 16261returning an integer type. In the latter case, the returned integer 16262value is the return code of the program (overriding any value that 16263may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 16264 16265 16266@itemize * 16267 16268@item 16269"The mechanisms for building and running partitions. See 1627010.2(24)." 16271@end itemize 16272 16273GNAT itself supports programs with only a single partition. The GNATDIST 16274tool provided with the GLADE package (which also includes an implementation 16275of the PCS) provides a completely flexible method for building and running 16276programs consisting of multiple partitions. See the separate GLADE manual 16277for details. 16278 16279 16280@itemize * 16281 16282@item 16283"The details of program execution, including program 16284termination. See 10.2(25)." 16285@end itemize 16286 16287See separate section on compilation model. 16288 16289 16290@itemize * 16291 16292@item 16293"The semantics of any non-active partitions supported by the 16294implementation. See 10.2(28)." 16295@end itemize 16296 16297Passive partitions are supported on targets where shared memory is 16298provided by the operating system. See the GLADE reference manual for 16299further details. 16300 16301 16302@itemize * 16303 16304@item 16305"The information returned by @code{Exception_Message}. See 1630611.4.1(10)." 16307@end itemize 16308 16309Exception message returns the null string unless a specific message has 16310been passed by the program. 16311 16312 16313@itemize * 16314 16315@item 16316"The result of @code{Exceptions.Exception_Name} for types 16317declared within an unnamed @emph{block_statement}. See 11.4.1(12)." 16318@end itemize 16319 16320Blocks have implementation defined names of the form @code{B@emph{nnn}} 16321where @emph{nnn} is an integer. 16322 16323 16324@itemize * 16325 16326@item 16327"The information returned by 16328@code{Exception_Information}. See 11.4.1(13)." 16329@end itemize 16330 16331@code{Exception_Information} returns a string in the following format: 16332 16333@example 16334*Exception_Name:* nnnnn 16335*Message:* mmmmm 16336*PID:* ppp 16337*Load address:* 0xhhhh 16338*Call stack traceback locations:* 163390xhhhh 0xhhhh 0xhhhh ... 0xhhh 16340@end example 16341 16342where 16343 16344@quotation 16345 16346 16347@itemize * 16348 16349@item 16350@code{nnnn} is the fully qualified name of the exception in all upper 16351case letters. This line is always present. 16352 16353@item 16354@code{mmmm} is the message (this line present only if message is non-null) 16355 16356@item 16357@code{ppp} is the Process Id value as a decimal integer (this line is 16358present only if the Process Id is nonzero). Currently we are 16359not making use of this field. 16360 16361@item 16362The Load address line, the Call stack traceback locations line and the 16363following values are present only if at least one traceback location was 16364recorded. The Load address indicates the address at which the main executable 16365was loaded; this line may not be present if operating system hasn't relocated 16366the main executable. The values are given in C style format, with lower case 16367letters for a-f, and only as many digits present as are necessary. 16368The line terminator sequence at the end of each line, including 16369the last line is a single @code{LF} character (@code{16#0A#}). 16370@end itemize 16371@end quotation 16372 16373 16374@itemize * 16375 16376@item 16377"Implementation-defined check names. See 11.5(27)." 16378@end itemize 16379 16380The implementation defined check names include Alignment_Check, 16381Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 16382Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 16383program can add implementation-defined check names by means of the pragma 16384Check_Name. See the description of pragma @code{Suppress} for full details. 16385 16386 16387@itemize * 16388 16389@item 16390"The interpretation of each aspect of representation. See 1639113.1(20)." 16392@end itemize 16393 16394See separate section on data representations. 16395 16396 16397@itemize * 16398 16399@item 16400"Any restrictions placed upon representation items. See 1640113.1(20)." 16402@end itemize 16403 16404See separate section on data representations. 16405 16406 16407@itemize * 16408 16409@item 16410"The meaning of @code{Size} for indefinite subtypes. See 1641113.3(48)." 16412@end itemize 16413 16414Size for an indefinite subtype is the maximum possible size, except that 16415for the case of a subprogram parameter, the size of the parameter object 16416is the actual size. 16417 16418 16419@itemize * 16420 16421@item 16422"The default external representation for a type tag. See 1642313.3(75)." 16424@end itemize 16425 16426The default external representation for a type tag is the fully expanded 16427name of the type in upper case letters. 16428 16429 16430@itemize * 16431 16432@item 16433"What determines whether a compilation unit is the same in 16434two different partitions. See 13.3(76)." 16435@end itemize 16436 16437A compilation unit is the same in two different partitions if and only 16438if it derives from the same source file. 16439 16440 16441@itemize * 16442 16443@item 16444"Implementation-defined components. See 13.5.1(15)." 16445@end itemize 16446 16447The only implementation defined component is the tag for a tagged type, 16448which contains a pointer to the dispatching table. 16449 16450 16451@itemize * 16452 16453@item 16454"If @code{Word_Size} = @code{Storage_Unit}, the default bit 16455ordering. See 13.5.3(5)." 16456@end itemize 16457 16458@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 16459implementation, so no non-default bit ordering is supported. The default 16460bit ordering corresponds to the natural endianness of the target architecture. 16461 16462 16463@itemize * 16464 16465@item 16466"The contents of the visible part of package @code{System} 16467and its language-defined children. See 13.7(2)." 16468@end itemize 16469 16470See the definition of these packages in files @code{system.ads} and 16471@code{s-stoele.ads}. Note that two declarations are added to package 16472System. 16473 16474@example 16475Max_Priority : constant Positive := Priority'Last; 16476Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 16477@end example 16478 16479 16480@itemize * 16481 16482@item 16483"The contents of the visible part of package 16484@code{System.Machine_Code}, and the meaning of 16485@emph{code_statements}. See 13.8(7)." 16486@end itemize 16487 16488See the definition and documentation in file @code{s-maccod.ads}. 16489 16490 16491@itemize * 16492 16493@item 16494"The effect of unchecked conversion. See 13.9(11)." 16495@end itemize 16496 16497Unchecked conversion between types of the same size 16498results in an uninterpreted transmission of the bits from one type 16499to the other. If the types are of unequal sizes, then in the case of 16500discrete types, a shorter source is first zero or sign extended as 16501necessary, and a shorter target is simply truncated on the left. 16502For all non-discrete types, the source is first copied if necessary 16503to ensure that the alignment requirements of the target are met, then 16504a pointer is constructed to the source value, and the result is obtained 16505by dereferencing this pointer after converting it to be a pointer to the 16506target type. Unchecked conversions where the target subtype is an 16507unconstrained array are not permitted. If the target alignment is 16508greater than the source alignment, then a copy of the result is 16509made with appropriate alignment 16510 16511 16512@itemize * 16513 16514@item 16515"The semantics of operations on invalid representations. 16516See 13.9.2(10-11)." 16517@end itemize 16518 16519For assignments and other operations where the use of invalid values cannot 16520result in erroneous behavior, the compiler ignores the possibility of invalid 16521values. An exception is raised at the point where an invalid value would 16522result in erroneous behavior. For example executing: 16523 16524@example 16525procedure invalidvals is 16526 X : Integer := -1; 16527 Y : Natural range 1 .. 10; 16528 for Y'Address use X'Address; 16529 Z : Natural range 1 .. 10; 16530 A : array (Natural range 1 .. 10) of Integer; 16531begin 16532 Z := Y; -- no exception 16533 A (Z) := 3; -- exception raised; 16534end; 16535@end example 16536 16537As indicated, an exception is raised on the array assignment, but not 16538on the simple assignment of the invalid negative value from Y to Z. 16539 16540 16541@itemize * 16542 16543@item 16544"The manner of choosing a storage pool for an access type 16545when @code{Storage_Pool} is not specified for the type. See 13.11(17)." 16546@end itemize 16547 16548There are 3 different standard pools used by the compiler when 16549@code{Storage_Pool} is not specified depending whether the type is local 16550to a subprogram or defined at the library level and whether 16551@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime 16552library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and 16553@code{System.Pool_Local} in files @code{s-poosiz.ads}, 16554@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 16555default pools used. 16556 16557 16558@itemize * 16559 16560@item 16561"Whether or not the implementation provides user-accessible 16562names for the standard pool type(s). See 13.11(17)." 16563@end itemize 16564 16565See documentation in the sources of the run time mentioned in the previous 16566paragraph. All these pools are accessible by means of @cite{with}ing 16567these units. 16568 16569 16570@itemize * 16571 16572@item 16573"The meaning of @code{Storage_Size}. See 13.11(18)." 16574@end itemize 16575 16576@code{Storage_Size} is measured in storage units, and refers to the 16577total space available for an access type collection, or to the primary 16578stack space for a task. 16579 16580 16581@itemize * 16582 16583@item 16584"Implementation-defined aspects of storage pools. See 1658513.11(22)." 16586@end itemize 16587 16588See documentation in the sources of the run time mentioned in the 16589paragraph about standard storage pools above 16590for details on GNAT-defined aspects of storage pools. 16591 16592 16593@itemize * 16594 16595@item 16596"The set of restrictions allowed in a pragma 16597@code{Restrictions}. See 13.12(7)." 16598@end itemize 16599 16600See @ref{9,,Standard and Implementation Defined Restrictions}. 16601 16602 16603@itemize * 16604 16605@item 16606"The consequences of violating limitations on 16607@code{Restrictions} pragmas. See 13.12(9)." 16608@end itemize 16609 16610Restrictions that can be checked at compile time result in illegalities 16611if violated. Currently there are no other consequences of violating 16612restrictions. 16613 16614 16615@itemize * 16616 16617@item 16618"The representation used by the @code{Read} and 16619@code{Write} attributes of elementary types in terms of stream 16620elements. See 13.13.2(9)." 16621@end itemize 16622 16623The representation is the in-memory representation of the base type of 16624the type, using the number of bits corresponding to the 16625@code{type'Size} value, and the natural ordering of the machine. 16626 16627 16628@itemize * 16629 16630@item 16631"The names and characteristics of the numeric subtypes 16632declared in the visible part of package @code{Standard}. See A.1(3)." 16633@end itemize 16634 16635See items describing the integer and floating-point types supported. 16636 16637 16638@itemize * 16639 16640@item 16641"The string returned by @code{Character_Set_Version}. 16642See A.3.5(3)." 16643@end itemize 16644 16645@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns 16646the string "Unicode 4.0", referring to version 4.0 of the 16647Unicode specification. 16648 16649 16650@itemize * 16651 16652@item 16653"The accuracy actually achieved by the elementary 16654functions. See A.5.1(1)." 16655@end itemize 16656 16657The elementary functions correspond to the functions available in the C 16658library. Only fast math mode is implemented. 16659 16660 16661@itemize * 16662 16663@item 16664"The sign of a zero result from some of the operators or 16665functions in @code{Numerics.Generic_Elementary_Functions}, when 16666@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)." 16667@end itemize 16668 16669The sign of zeroes follows the requirements of the IEEE 754 standard on 16670floating-point. 16671 16672 16673@itemize * 16674 16675@item 16676"The value of 16677@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)." 16678@end itemize 16679 16680Maximum image width is 6864, see library file @code{s-rannum.ads}. 16681 16682 16683@itemize * 16684 16685@item 16686"The value of 16687@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)." 16688@end itemize 16689 16690Maximum image width is 6864, see library file @code{s-rannum.ads}. 16691 16692 16693@itemize * 16694 16695@item 16696"The algorithms for random number generation. See 16697A.5.2(32)." 16698@end itemize 16699 16700The algorithm is the Mersenne Twister, as documented in the source file 16701@code{s-rannum.adb}. This version of the algorithm has a period of 167022**19937-1. 16703 16704 16705@itemize * 16706 16707@item 16708"The string representation of a random number generator's 16709state. See A.5.2(38)." 16710@end itemize 16711 16712The value returned by the Image function is the concatenation of 16713the fixed-width decimal representations of the 624 32-bit integers 16714of the state vector. 16715 16716 16717@itemize * 16718 16719@item 16720"The minimum time interval between calls to the 16721time-dependent Reset procedure that are guaranteed to initiate different 16722random number sequences. See A.5.2(45)." 16723@end itemize 16724 16725The minimum period between reset calls to guarantee distinct series of 16726random numbers is one microsecond. 16727 16728 16729@itemize * 16730 16731@item 16732"The values of the @code{Model_Mantissa}, 16733@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 16734@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 16735Annex is not supported. See A.5.3(72)." 16736@end itemize 16737 16738Run the compiler with @emph{-gnatS} to produce a listing of package 16739@code{Standard}, has the values of all numeric attributes. 16740 16741 16742@itemize * 16743 16744@item 16745"Any implementation-defined characteristics of the 16746input-output packages. See A.7(14)." 16747@end itemize 16748 16749There are no special implementation defined characteristics for these 16750packages. 16751 16752 16753@itemize * 16754 16755@item 16756"The value of @code{Buffer_Size} in @code{Storage_IO}. See 16757A.9(10)." 16758@end itemize 16759 16760All type representations are contiguous, and the @code{Buffer_Size} is 16761the value of @code{type'Size} rounded up to the next storage unit 16762boundary. 16763 16764 16765@itemize * 16766 16767@item 16768"External files for standard input, standard output, and 16769standard error See A.10(5)." 16770@end itemize 16771 16772These files are mapped onto the files provided by the C streams 16773libraries. See source file @code{i-cstrea.ads} for further details. 16774 16775 16776@itemize * 16777 16778@item 16779"The accuracy of the value produced by @code{Put}. See 16780A.10.9(36)." 16781@end itemize 16782 16783If more digits are requested in the output than are represented by the 16784precision of the value, zeroes are output in the corresponding least 16785significant digit positions. 16786 16787 16788@itemize * 16789 16790@item 16791"The meaning of @code{Argument_Count}, @code{Argument}, and 16792@code{Command_Name}. See A.15(1)." 16793@end itemize 16794 16795These are mapped onto the @code{argv} and @code{argc} parameters of the 16796main program in the natural manner. 16797 16798 16799@itemize * 16800 16801@item 16802"The interpretation of the @code{Form} parameter in procedure 16803@code{Create_Directory}. See A.16(56)." 16804@end itemize 16805 16806The @code{Form} parameter is not used. 16807 16808 16809@itemize * 16810 16811@item 16812"The interpretation of the @code{Form} parameter in procedure 16813@code{Create_Path}. See A.16(60)." 16814@end itemize 16815 16816The @code{Form} parameter is not used. 16817 16818 16819@itemize * 16820 16821@item 16822"The interpretation of the @code{Form} parameter in procedure 16823@code{Copy_File}. See A.16(68)." 16824@end itemize 16825 16826The @code{Form} parameter is case-insensitive. 16827Two fields are recognized in the @code{Form} parameter: 16828 16829@example 16830*preserve=<value>* 16831*mode=<value>* 16832@end example 16833 16834<value> starts immediately after the character '=' and ends with the 16835character immediately preceding the next comma (',') or with the last 16836character of the parameter. 16837 16838The only possible values for preserve= are: 16839 16840 16841@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16842@headitem 16843 16844Value 16845 16846@tab 16847 16848Meaning 16849 16850@item 16851 16852@emph{no_attributes} 16853 16854@tab 16855 16856Do not try to preserve any file attributes. This is the 16857default if no preserve= is found in Form. 16858 16859@item 16860 16861@emph{all_attributes} 16862 16863@tab 16864 16865Try to preserve all file attributes (timestamps, access rights). 16866 16867@item 16868 16869@emph{timestamps} 16870 16871@tab 16872 16873Preserve the timestamp of the copied file, but not the other 16874file attributes. 16875 16876@end multitable 16877 16878 16879The only possible values for mode= are: 16880 16881 16882@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16883@headitem 16884 16885Value 16886 16887@tab 16888 16889Meaning 16890 16891@item 16892 16893@emph{copy} 16894 16895@tab 16896 16897Only do the copy if the destination file does not already exist. 16898If it already exists, Copy_File fails. 16899 16900@item 16901 16902@emph{overwrite} 16903 16904@tab 16905 16906Copy the file in all cases. Overwrite an already existing destination file. 16907 16908@item 16909 16910@emph{append} 16911 16912@tab 16913 16914Append the original file to the destination file. If the destination file 16915does not exist, the destination file is a copy of the source file. 16916When mode=append, the field preserve=, if it exists, is not taken into account. 16917 16918@end multitable 16919 16920 16921If the Form parameter includes one or both of the fields and the value or 16922values are incorrect, Copy_file fails with Use_Error. 16923 16924Examples of correct Forms: 16925 16926@example 16927Form => "preserve=no_attributes,mode=overwrite" (the default) 16928Form => "mode=append" 16929Form => "mode=copy, preserve=all_attributes" 16930@end example 16931 16932Examples of incorrect Forms: 16933 16934@example 16935Form => "preserve=junk" 16936Form => "mode=internal, preserve=timestamps" 16937@end example 16938 16939 16940@itemize * 16941 16942@item 16943"The interpretation of the @code{Pattern} parameter, when not the null string, 16944in the @code{Start_Search} and @code{Search} procedures. 16945See A.16(104) and A.16(112)." 16946@end itemize 16947 16948When the @code{Pattern} parameter is not the null string, it is interpreted 16949according to the syntax of regular expressions as defined in the 16950@code{GNAT.Regexp} package. 16951 16952See @ref{255,,GNAT.Regexp (g-regexp.ads)}. 16953 16954 16955@itemize * 16956 16957@item 16958"Implementation-defined convention names. See B.1(11)." 16959@end itemize 16960 16961The following convention names are supported 16962 16963 16964@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16965@headitem 16966 16967Convention Name 16968 16969@tab 16970 16971Interpretation 16972 16973@item 16974 16975@emph{Ada} 16976 16977@tab 16978 16979Ada 16980 16981@item 16982 16983@emph{Ada_Pass_By_Copy} 16984 16985@tab 16986 16987Allowed for any types except by-reference types such as limited 16988records. Compatible with convention Ada, but causes any parameters 16989with this convention to be passed by copy. 16990 16991@item 16992 16993@emph{Ada_Pass_By_Reference} 16994 16995@tab 16996 16997Allowed for any types except by-copy types such as scalars. 16998Compatible with convention Ada, but causes any parameters 16999with this convention to be passed by reference. 17000 17001@item 17002 17003@emph{Assembler} 17004 17005@tab 17006 17007Assembly language 17008 17009@item 17010 17011@emph{Asm} 17012 17013@tab 17014 17015Synonym for Assembler 17016 17017@item 17018 17019@emph{Assembly} 17020 17021@tab 17022 17023Synonym for Assembler 17024 17025@item 17026 17027@emph{C} 17028 17029@tab 17030 17031C 17032 17033@item 17034 17035@emph{C_Pass_By_Copy} 17036 17037@tab 17038 17039Allowed only for record types, like C, but also notes that record 17040is to be passed by copy rather than reference. 17041 17042@item 17043 17044@emph{COBOL} 17045 17046@tab 17047 17048COBOL 17049 17050@item 17051 17052@emph{C_Plus_Plus (or CPP)} 17053 17054@tab 17055 17056C++ 17057 17058@item 17059 17060@emph{Default} 17061 17062@tab 17063 17064Treated the same as C 17065 17066@item 17067 17068@emph{External} 17069 17070@tab 17071 17072Treated the same as C 17073 17074@item 17075 17076@emph{Fortran} 17077 17078@tab 17079 17080Fortran 17081 17082@item 17083 17084@emph{Intrinsic} 17085 17086@tab 17087 17088For support of pragma @code{Import} with convention Intrinsic, see 17089separate section on Intrinsic Subprograms. 17090 17091@item 17092 17093@emph{Stdcall} 17094 17095@tab 17096 17097Stdcall (used for Windows implementations only). This convention correspond 17098to the WINAPI (previously called Pascal convention) C/C++ convention under 17099Windows. A routine with this convention cleans the stack before 17100exit. This pragma cannot be applied to a dispatching call. 17101 17102@item 17103 17104@emph{DLL} 17105 17106@tab 17107 17108Synonym for Stdcall 17109 17110@item 17111 17112@emph{Win32} 17113 17114@tab 17115 17116Synonym for Stdcall 17117 17118@item 17119 17120@emph{Stubbed} 17121 17122@tab 17123 17124Stubbed is a special convention used to indicate that the body of the 17125subprogram will be entirely ignored. Any call to the subprogram 17126is converted into a raise of the @code{Program_Error} exception. If a 17127pragma @code{Import} specifies convention @code{stubbed} then no body need 17128be present at all. This convention is useful during development for the 17129inclusion of subprograms whose body has not yet been written. 17130In addition, all otherwise unrecognized convention names are also 17131treated as being synonymous with convention C. In all implementations 17132except for VMS, use of such other names results in a warning. In VMS 17133implementations, these names are accepted silently. 17134 17135@end multitable 17136 17137 17138 17139@itemize * 17140 17141@item 17142"The meaning of link names. See B.1(36)." 17143@end itemize 17144 17145Link names are the actual names used by the linker. 17146 17147 17148@itemize * 17149 17150@item 17151"The manner of choosing link names when neither the link 17152name nor the address of an imported or exported entity is specified. See 17153B.1(36)." 17154@end itemize 17155 17156The default linker name is that which would be assigned by the relevant 17157external language, interpreting the Ada name as being in all lower case 17158letters. 17159 17160 17161@itemize * 17162 17163@item 17164"The effect of pragma @code{Linker_Options}. See B.1(37)." 17165@end itemize 17166 17167The string passed to @code{Linker_Options} is presented uninterpreted as 17168an argument to the link command, unless it contains ASCII.NUL characters. 17169NUL characters if they appear act as argument separators, so for example 17170 17171@example 17172pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 17173@end example 17174 17175causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 17176linker. The order of linker options is preserved for a given unit. The final 17177list of options passed to the linker is in reverse order of the elaboration 17178order. For example, linker options for a body always appear before the options 17179from the corresponding package spec. 17180 17181 17182@itemize * 17183 17184@item 17185"The contents of the visible part of package 17186@code{Interfaces} and its language-defined descendants. See B.2(1)." 17187@end itemize 17188 17189See files with prefix @code{i-} in the distributed library. 17190 17191 17192@itemize * 17193 17194@item 17195"Implementation-defined children of package 17196@code{Interfaces}. The contents of the visible part of package 17197@code{Interfaces}. See B.2(11)." 17198@end itemize 17199 17200See files with prefix @code{i-} in the distributed library. 17201 17202 17203@itemize * 17204 17205@item 17206"The types @code{Floating}, @code{Long_Floating}, 17207@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 17208@code{COBOL_Character}; and the initialization of the variables 17209@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 17210@code{Interfaces.COBOL}. See B.4(50)." 17211@end itemize 17212 17213 17214@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17215@headitem 17216 17217COBOL 17218 17219@tab 17220 17221Ada 17222 17223@item 17224 17225@emph{Floating} 17226 17227@tab 17228 17229Float 17230 17231@item 17232 17233@emph{Long_Floating} 17234 17235@tab 17236 17237(Floating) Long_Float 17238 17239@item 17240 17241@emph{Binary} 17242 17243@tab 17244 17245Integer 17246 17247@item 17248 17249@emph{Long_Binary} 17250 17251@tab 17252 17253Long_Long_Integer 17254 17255@item 17256 17257@emph{Decimal_Element} 17258 17259@tab 17260 17261Character 17262 17263@item 17264 17265@emph{COBOL_Character} 17266 17267@tab 17268 17269Character 17270 17271@end multitable 17272 17273 17274For initialization, see the file @code{i-cobol.ads} in the distributed library. 17275 17276 17277@itemize * 17278 17279@item 17280"Support for access to machine instructions. See C.1(1)." 17281@end itemize 17282 17283See documentation in file @code{s-maccod.ads} in the distributed library. 17284 17285 17286@itemize * 17287 17288@item 17289"Implementation-defined aspects of access to machine 17290operations. See C.1(9)." 17291@end itemize 17292 17293See documentation in file @code{s-maccod.ads} in the distributed library. 17294 17295 17296@itemize * 17297 17298@item 17299"Implementation-defined aspects of interrupts. See C.3(2)." 17300@end itemize 17301 17302Interrupts are mapped to signals or conditions as appropriate. See 17303definition of unit 17304@code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details 17305on the interrupts supported on a particular target. 17306 17307 17308@itemize * 17309 17310@item 17311"Implementation-defined aspects of pre-elaboration. See 17312C.4(13)." 17313@end itemize 17314 17315GNAT does not permit a partition to be restarted without reloading, 17316except under control of the debugger. 17317 17318 17319@itemize * 17320 17321@item 17322"The semantics of pragma @code{Discard_Names}. See C.5(7)." 17323@end itemize 17324 17325Pragma @code{Discard_Names} causes names of enumeration literals to 17326be suppressed. In the presence of this pragma, the Image attribute 17327provides the image of the Pos of the literal, and Value accepts 17328Pos values. 17329 17330For tagged types, when pragmas @code{Discard_Names} and @code{No_Tagged_Streams} 17331simultaneously apply, their Expanded_Name and External_Tag are initialized 17332with empty strings. This is useful to avoid exposing entity names at binary 17333level. 17334 17335 17336@itemize * 17337 17338@item 17339"The result of the @code{Task_Identification.Image} 17340attribute. See C.7.1(7)." 17341@end itemize 17342 17343The result of this attribute is a string that identifies 17344the object or component that denotes a given task. If a variable @code{Var} 17345has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, 17346where the suffix @emph{XXXXXXXX} 17347is the hexadecimal representation of the virtual address of the corresponding 17348task control block. If the variable is an array of tasks, the image of each 17349task will have the form of an indexed component indicating the position of a 17350given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a 17351component of a record, the image of the task will have the form of a selected 17352component. These rules are fully recursive, so that the image of a task that 17353is a subcomponent of a composite object corresponds to the expression that 17354designates this task. 17355 17356If a task is created by an allocator, its image depends on the context. If the 17357allocator is part of an object declaration, the rules described above are used 17358to construct its image, and this image is not affected by subsequent 17359assignments. If the allocator appears within an expression, the image 17360includes only the name of the task type. 17361 17362If the configuration pragma Discard_Names is present, or if the restriction 17363No_Implicit_Heap_Allocation is in effect, the image reduces to 17364the numeric suffix, that is to say the hexadecimal representation of the 17365virtual address of the control block of the task. 17366 17367 17368@itemize * 17369 17370@item 17371"The value of @code{Current_Task} when in a protected entry 17372or interrupt handler. See C.7.1(17)." 17373@end itemize 17374 17375Protected entries or interrupt handlers can be executed by any 17376convenient thread, so the value of @code{Current_Task} is undefined. 17377 17378 17379@itemize * 17380 17381@item 17382"The effect of calling @code{Current_Task} from an entry 17383body or interrupt handler. See C.7.1(19)." 17384@end itemize 17385 17386When GNAT can determine statically that @code{Current_Task} is called directly in 17387the body of an entry (or barrier) then a warning is emitted and @code{Program_Error} 17388is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an 17389entry body or interrupt handler is to return the identification of the task 17390currently executing the code. 17391 17392 17393@itemize * 17394 17395@item 17396"Implementation-defined aspects of 17397@code{Task_Attributes}. See C.7.2(19)." 17398@end itemize 17399 17400There are no implementation-defined aspects of @code{Task_Attributes}. 17401 17402 17403@itemize * 17404 17405@item 17406"Values of all @code{Metrics}. See D(2)." 17407@end itemize 17408 17409The metrics information for GNAT depends on the performance of the 17410underlying operating system. The sources of the run-time for tasking 17411implementation, together with the output from @emph{-gnatG} can be 17412used to determine the exact sequence of operating systems calls made 17413to implement various tasking constructs. Together with appropriate 17414information on the performance of the underlying operating system, 17415on the exact target in use, this information can be used to determine 17416the required metrics. 17417 17418 17419@itemize * 17420 17421@item 17422"The declarations of @code{Any_Priority} and 17423@code{Priority}. See D.1(11)." 17424@end itemize 17425 17426See declarations in file @code{system.ads}. 17427 17428 17429@itemize * 17430 17431@item 17432"Implementation-defined execution resources. See D.1(15)." 17433@end itemize 17434 17435There are no implementation-defined execution resources. 17436 17437 17438@itemize * 17439 17440@item 17441"Whether, on a multiprocessor, a task that is waiting for 17442access to a protected object keeps its processor busy. See D.2.1(3)." 17443@end itemize 17444 17445On a multi-processor, a task that is waiting for access to a protected 17446object does not keep its processor busy. 17447 17448 17449@itemize * 17450 17451@item 17452"The affect of implementation defined execution resources 17453on task dispatching. See D.2.1(9)." 17454@end itemize 17455 17456Tasks map to threads in the threads package used by GNAT. Where possible 17457and appropriate, these threads correspond to native threads of the 17458underlying operating system. 17459 17460 17461@itemize * 17462 17463@item 17464"Implementation-defined @emph{policy_identifiers} allowed 17465in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)." 17466@end itemize 17467 17468There are no implementation-defined policy-identifiers allowed in this 17469pragma. 17470 17471 17472@itemize * 17473 17474@item 17475"Implementation-defined aspects of priority inversion. See 17476D.2.2(16)." 17477@end itemize 17478 17479Execution of a task cannot be preempted by the implementation processing 17480of delay expirations for lower priority tasks. 17481 17482 17483@itemize * 17484 17485@item 17486"Implementation-defined task dispatching. See D.2.2(18)." 17487@end itemize 17488 17489The policy is the same as that of the underlying threads implementation. 17490 17491 17492@itemize * 17493 17494@item 17495"Implementation-defined @emph{policy_identifiers} allowed 17496in a pragma @code{Locking_Policy}. See D.3(4)." 17497@end itemize 17498 17499The two implementation defined policies permitted in GNAT are 17500@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On 17501targets that support the @code{Inheritance_Locking} policy, locking is 17502implemented by inheritance, i.e., the task owning the lock operates 17503at a priority equal to the highest priority of any task currently 17504requesting the lock. On targets that support the 17505@code{Concurrent_Readers_Locking} policy, locking is implemented with a 17506read/write lock allowing multiple protected object functions to enter 17507concurrently. 17508 17509 17510@itemize * 17511 17512@item 17513"Default ceiling priorities. See D.3(10)." 17514@end itemize 17515 17516The ceiling priority of protected objects of the type 17517@code{System.Interrupt_Priority'Last} as described in the Ada 17518Reference Manual D.3(10), 17519 17520 17521@itemize * 17522 17523@item 17524"The ceiling of any protected object used internally by 17525the implementation. See D.3(16)." 17526@end itemize 17527 17528The ceiling priority of internal protected objects is 17529@code{System.Priority'Last}. 17530 17531 17532@itemize * 17533 17534@item 17535"Implementation-defined queuing policies. See D.4(1)." 17536@end itemize 17537 17538There are no implementation-defined queuing policies. 17539 17540 17541@itemize * 17542 17543@item 17544"On a multiprocessor, any conditions that cause the 17545completion of an aborted construct to be delayed later than what is 17546specified for a single processor. See D.6(3)." 17547@end itemize 17548 17549The semantics for abort on a multi-processor is the same as on a single 17550processor, there are no further delays. 17551 17552 17553@itemize * 17554 17555@item 17556"Any operations that implicitly require heap storage 17557allocation. See D.7(8)." 17558@end itemize 17559 17560The only operation that implicitly requires heap storage allocation is 17561task creation. 17562 17563 17564@itemize * 17565 17566@item 17567"What happens when a task terminates in the presence of 17568pragma @code{No_Task_Termination}. See D.7(15)." 17569@end itemize 17570 17571Execution is erroneous in that case. 17572 17573 17574@itemize * 17575 17576@item 17577"Implementation-defined aspects of pragma 17578@code{Restrictions}. See D.7(20)." 17579@end itemize 17580 17581There are no such implementation-defined aspects. 17582 17583 17584@itemize * 17585 17586@item 17587"Implementation-defined aspects of package 17588@code{Real_Time}. See D.8(17)." 17589@end itemize 17590 17591There are no implementation defined aspects of package @code{Real_Time}. 17592 17593 17594@itemize * 17595 17596@item 17597"Implementation-defined aspects of 17598@emph{delay_statements}. See D.9(8)." 17599@end itemize 17600 17601Any difference greater than one microsecond will cause the task to be 17602delayed (see D.9(7)). 17603 17604 17605@itemize * 17606 17607@item 17608"The upper bound on the duration of interrupt blocking 17609caused by the implementation. See D.12(5)." 17610@end itemize 17611 17612The upper bound is determined by the underlying operating system. In 17613no cases is it more than 10 milliseconds. 17614 17615 17616@itemize * 17617 17618@item 17619"The means for creating and executing distributed 17620programs. See E(5)." 17621@end itemize 17622 17623The GLADE package provides a utility GNATDIST for creating and executing 17624distributed programs. See the GLADE reference manual for further details. 17625 17626 17627@itemize * 17628 17629@item 17630"Any events that can result in a partition becoming 17631inaccessible. See E.1(7)." 17632@end itemize 17633 17634See the GLADE reference manual for full details on such events. 17635 17636 17637@itemize * 17638 17639@item 17640"The scheduling policies, treatment of priorities, and 17641management of shared resources between partitions in certain cases. See 17642E.1(11)." 17643@end itemize 17644 17645See the GLADE reference manual for full details on these aspects of 17646multi-partition execution. 17647 17648 17649@itemize * 17650 17651@item 17652"Events that cause the version of a compilation unit to 17653change. See E.3(5)." 17654@end itemize 17655 17656Editing the source file of a compilation unit, or the source files of 17657any units on which it is dependent in a significant way cause the version 17658to change. No other actions cause the version number to change. All changes 17659are significant except those which affect only layout, capitalization or 17660comments. 17661 17662 17663@itemize * 17664 17665@item 17666"Whether the execution of the remote subprogram is 17667immediately aborted as a result of cancellation. See E.4(13)." 17668@end itemize 17669 17670See the GLADE reference manual for details on the effect of abort in 17671a distributed application. 17672 17673 17674@itemize * 17675 17676@item 17677"Implementation-defined aspects of the PCS. See E.5(25)." 17678@end itemize 17679 17680See the GLADE reference manual for a full description of all implementation 17681defined aspects of the PCS. 17682 17683 17684@itemize * 17685 17686@item 17687"Implementation-defined interfaces in the PCS. See 17688E.5(26)." 17689@end itemize 17690 17691See the GLADE reference manual for a full description of all 17692implementation defined interfaces. 17693 17694 17695@itemize * 17696 17697@item 17698"The values of named numbers in the package 17699@code{Decimal}. See F.2(7)." 17700@end itemize 17701 17702 17703@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17704@headitem 17705 17706Named Number 17707 17708@tab 17709 17710Value 17711 17712@item 17713 17714@emph{Max_Scale} 17715 17716@tab 17717 17718+18 17719 17720@item 17721 17722@emph{Min_Scale} 17723 17724@tab 17725 17726-18 17727 17728@item 17729 17730@emph{Min_Delta} 17731 17732@tab 17733 177341.0E-18 17735 17736@item 17737 17738@emph{Max_Delta} 17739 17740@tab 17741 177421.0E+18 17743 17744@item 17745 17746@emph{Max_Decimal_Digits} 17747 17748@tab 17749 1775018 17751 17752@end multitable 17753 17754 17755 17756@itemize * 17757 17758@item 17759"The value of @code{Max_Picture_Length} in the package 17760@code{Text_IO.Editing}. See F.3.3(16)." 17761@end itemize 17762 1776364 17764 17765 17766@itemize * 17767 17768@item 17769"The value of @code{Max_Picture_Length} in the package 17770@code{Wide_Text_IO.Editing}. See F.3.4(5)." 17771@end itemize 17772 1777364 17774 17775 17776@itemize * 17777 17778@item 17779"The accuracy actually achieved by the complex elementary 17780functions and by other complex arithmetic operations. See G.1(1)." 17781@end itemize 17782 17783Standard library functions are used for the complex arithmetic 17784operations. Only fast math mode is currently supported. 17785 17786 17787@itemize * 17788 17789@item 17790"The sign of a zero result (or a component thereof) from 17791any operator or function in @code{Numerics.Generic_Complex_Types}, when 17792@code{Real'Signed_Zeros} is True. See G.1.1(53)." 17793@end itemize 17794 17795The signs of zero values are as recommended by the relevant 17796implementation advice. 17797 17798 17799@itemize * 17800 17801@item 17802"The sign of a zero result (or a component thereof) from 17803any operator or function in 17804@code{Numerics.Generic_Complex_Elementary_Functions}, when 17805@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)." 17806@end itemize 17807 17808The signs of zero values are as recommended by the relevant 17809implementation advice. 17810 17811 17812@itemize * 17813 17814@item 17815"Whether the strict mode or the relaxed mode is the 17816default. See G.2(2)." 17817@end itemize 17818 17819The strict mode is the default. There is no separate relaxed mode. GNAT 17820provides a highly efficient implementation of strict mode. 17821 17822 17823@itemize * 17824 17825@item 17826"The result interval in certain cases of fixed-to-float 17827conversion. See G.2.1(10)." 17828@end itemize 17829 17830For cases where the result interval is implementation dependent, the 17831accuracy is that provided by performing all operations in 64-bit IEEE 17832floating-point format. 17833 17834 17835@itemize * 17836 17837@item 17838"The result of a floating point arithmetic operation in 17839overflow situations, when the @code{Machine_Overflows} attribute of the 17840result type is @code{False}. See G.2.1(13)." 17841@end itemize 17842 17843Infinite and NaN values are produced as dictated by the IEEE 17844floating-point standard. 17845Note that on machines that are not fully compliant with the IEEE 17846floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 17847must be used for achieving IEEE conforming behavior (although at the cost 17848of a significant performance penalty), so infinite and NaN values are 17849properly generated. 17850 17851 17852@itemize * 17853 17854@item 17855"The result interval for division (or exponentiation by a 17856negative exponent), when the floating point hardware implements division 17857as multiplication by a reciprocal. See G.2.1(16)." 17858@end itemize 17859 17860Not relevant, division is IEEE exact. 17861 17862 17863@itemize * 17864 17865@item 17866"The definition of close result set, which determines the 17867accuracy of certain fixed point multiplications and divisions. See 17868G.2.3(5)." 17869@end itemize 17870 17871Operations in the close result set are performed using IEEE long format 17872floating-point arithmetic. The input operands are converted to 17873floating-point, the operation is done in floating-point, and the result 17874is converted to the target type. 17875 17876 17877@itemize * 17878 17879@item 17880"Conditions on a @emph{universal_real} operand of a fixed 17881point multiplication or division for which the result shall be in the 17882perfect result set. See G.2.3(22)." 17883@end itemize 17884 17885The result is only defined to be in the perfect result set if the result 17886can be computed by a single scaling operation involving a scale factor 17887representable in 64-bits. 17888 17889 17890@itemize * 17891 17892@item 17893"The result of a fixed point arithmetic operation in 17894overflow situations, when the @code{Machine_Overflows} attribute of the 17895result type is @code{False}. See G.2.3(27)." 17896@end itemize 17897 17898Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 17899types. 17900 17901 17902@itemize * 17903 17904@item 17905"The result of an elementary function reference in 17906overflow situations, when the @code{Machine_Overflows} attribute of the 17907result type is @code{False}. See G.2.4(4)." 17908@end itemize 17909 17910IEEE infinite and Nan values are produced as appropriate. 17911 17912 17913@itemize * 17914 17915@item 17916"The value of the angle threshold, within which certain 17917elementary functions, complex arithmetic operations, and complex 17918elementary functions yield results conforming to a maximum relative 17919error bound. See G.2.4(10)." 17920@end itemize 17921 17922Information on this subject is not yet available. 17923 17924 17925@itemize * 17926 17927@item 17928"The accuracy of certain elementary functions for 17929parameters beyond the angle threshold. See G.2.4(10)." 17930@end itemize 17931 17932Information on this subject is not yet available. 17933 17934 17935@itemize * 17936 17937@item 17938"The result of a complex arithmetic operation or complex 17939elementary function reference in overflow situations, when the 17940@code{Machine_Overflows} attribute of the corresponding real type is 17941@code{False}. See G.2.6(5)." 17942@end itemize 17943 17944IEEE infinite and Nan values are produced as appropriate. 17945 17946 17947@itemize * 17948 17949@item 17950"The accuracy of certain complex arithmetic operations and 17951certain complex elementary functions for parameters (or components 17952thereof) beyond the angle threshold. See G.2.6(8)." 17953@end itemize 17954 17955Information on those subjects is not yet available. 17956 17957 17958@itemize * 17959 17960@item 17961"Information regarding bounded errors and erroneous 17962execution. See H.2(1)." 17963@end itemize 17964 17965Information on this subject is not yet available. 17966 17967 17968@itemize * 17969 17970@item 17971"Implementation-defined aspects of pragma 17972@code{Inspection_Point}. See H.3.2(8)." 17973@end itemize 17974 17975Pragma @code{Inspection_Point} ensures that the variable is live and can 17976be examined by the debugger at the inspection point. 17977 17978 17979@itemize * 17980 17981@item 17982"Implementation-defined aspects of pragma 17983@code{Restrictions}. See H.4(25)." 17984@end itemize 17985 17986There are no implementation-defined aspects of pragma @code{Restrictions}. The 17987use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 17988generated code. Checks must suppressed by use of pragma @code{Suppress}. 17989 17990 17991@itemize * 17992 17993@item 17994"Any restrictions on pragma @code{Restrictions}. See 17995H.4(27)." 17996@end itemize 17997 17998There are no restrictions on pragma @code{Restrictions}. 17999 18000@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 18001@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{256}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{257} 18002@chapter Intrinsic Subprograms 18003 18004 18005@geindex Intrinsic Subprograms 18006 18007GNAT allows a user application program to write the declaration: 18008 18009@example 18010pragma Import (Intrinsic, name); 18011@end example 18012 18013providing that the name corresponds to one of the implemented intrinsic 18014subprograms in GNAT, and that the parameter profile of the referenced 18015subprogram meets the requirements. This chapter describes the set of 18016implemented intrinsic subprograms, and the requirements on parameter profiles. 18017Note that no body is supplied; as with other uses of pragma Import, the 18018body is supplied elsewhere (in this case by the compiler itself). Note 18019that any use of this feature is potentially non-portable, since the 18020Ada standard does not require Ada compilers to implement this feature. 18021 18022@menu 18023* Intrinsic Operators:: 18024* Compilation_ISO_Date:: 18025* Compilation_Date:: 18026* Compilation_Time:: 18027* Enclosing_Entity:: 18028* Exception_Information:: 18029* Exception_Message:: 18030* Exception_Name:: 18031* File:: 18032* Line:: 18033* Shifts and Rotates:: 18034* Source_Location:: 18035 18036@end menu 18037 18038@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms 18039@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{258}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{259} 18040@section Intrinsic Operators 18041 18042 18043@geindex Intrinsic operator 18044 18045All the predefined numeric operators in package Standard 18046in @code{pragma Import (Intrinsic,..)} 18047declarations. In the binary operator case, the operands must have the same 18048size. The operand or operands must also be appropriate for 18049the operator. For example, for addition, the operands must 18050both be floating-point or both be fixed-point, and the 18051right operand for @code{"**"} must have a root type of 18052@code{Standard.Integer'Base}. 18053You can use an intrinsic operator declaration as in the following example: 18054 18055@example 18056type Int1 is new Integer; 18057type Int2 is new Integer; 18058 18059function "+" (X1 : Int1; X2 : Int2) return Int1; 18060function "+" (X1 : Int1; X2 : Int2) return Int2; 18061pragma Import (Intrinsic, "+"); 18062@end example 18063 18064This declaration would permit 'mixed mode' arithmetic on items 18065of the differing types @code{Int1} and @code{Int2}. 18066It is also possible to specify such operators for private types, if the 18067full views are appropriate arithmetic types. 18068 18069@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms 18070@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{25a}@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{25b} 18071@section Compilation_ISO_Date 18072 18073 18074@geindex Compilation_ISO_Date 18075 18076This intrinsic subprogram is used in the implementation of the 18077library package @code{GNAT.Source_Info}. The only useful use of the 18078intrinsic import in this case is the one in this unit, so an 18079application program should simply call the function 18080@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of 18081the current compilation (in local time format YYYY-MM-DD). 18082 18083@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms 18084@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{25c}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{25d} 18085@section Compilation_Date 18086 18087 18088@geindex Compilation_Date 18089 18090Same as Compilation_ISO_Date, except the string is in the form 18091MMM DD YYYY. 18092 18093@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 18094@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{25f} 18095@section Compilation_Time 18096 18097 18098@geindex Compilation_Time 18099 18100This intrinsic subprogram is used in the implementation of the 18101library package @code{GNAT.Source_Info}. The only useful use of the 18102intrinsic import in this case is the one in this unit, so an 18103application program should simply call the function 18104@code{GNAT.Source_Info.Compilation_Time} to obtain the time of 18105the current compilation (in local time format HH:MM:SS). 18106 18107@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 18108@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{260}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{261} 18109@section Enclosing_Entity 18110 18111 18112@geindex Enclosing_Entity 18113 18114This intrinsic subprogram is used in the implementation of the 18115library package @code{GNAT.Source_Info}. The only useful use of the 18116intrinsic import in this case is the one in this unit, so an 18117application program should simply call the function 18118@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 18119the current subprogram, package, task, entry, or protected subprogram. 18120 18121@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 18122@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{262}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{263} 18123@section Exception_Information 18124 18125 18126@geindex Exception_Information' 18127 18128This intrinsic subprogram is used in the implementation of the 18129library package @code{GNAT.Current_Exception}. The only useful 18130use of the intrinsic import in this case is the one in this unit, 18131so an application program should simply call the function 18132@code{GNAT.Current_Exception.Exception_Information} to obtain 18133the exception information associated with the current exception. 18134 18135@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 18136@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{264}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{265} 18137@section Exception_Message 18138 18139 18140@geindex Exception_Message 18141 18142This intrinsic subprogram is used in the implementation of the 18143library package @code{GNAT.Current_Exception}. The only useful 18144use of the intrinsic import in this case is the one in this unit, 18145so an application program should simply call the function 18146@code{GNAT.Current_Exception.Exception_Message} to obtain 18147the message associated with the current exception. 18148 18149@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 18150@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{266}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{267} 18151@section Exception_Name 18152 18153 18154@geindex Exception_Name 18155 18156This intrinsic subprogram is used in the implementation of the 18157library package @code{GNAT.Current_Exception}. The only useful 18158use of the intrinsic import in this case is the one in this unit, 18159so an application program should simply call the function 18160@code{GNAT.Current_Exception.Exception_Name} to obtain 18161the name of the current exception. 18162 18163@node File,Line,Exception_Name,Intrinsic Subprograms 18164@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{268}@anchor{gnat_rm/intrinsic_subprograms file}@anchor{269} 18165@section File 18166 18167 18168@geindex File 18169 18170This intrinsic subprogram is used in the implementation of the 18171library package @code{GNAT.Source_Info}. The only useful use of the 18172intrinsic import in this case is the one in this unit, so an 18173application program should simply call the function 18174@code{GNAT.Source_Info.File} to obtain the name of the current 18175file. 18176 18177@node Line,Shifts and Rotates,File,Intrinsic Subprograms 18178@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{26b} 18179@section Line 18180 18181 18182@geindex Line 18183 18184This intrinsic subprogram is used in the implementation of the 18185library package @code{GNAT.Source_Info}. The only useful use of the 18186intrinsic import in this case is the one in this unit, so an 18187application program should simply call the function 18188@code{GNAT.Source_Info.Line} to obtain the number of the current 18189source line. 18190 18191@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 18192@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{26c}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{26d} 18193@section Shifts and Rotates 18194 18195 18196@geindex Shift_Left 18197 18198@geindex Shift_Right 18199 18200@geindex Shift_Right_Arithmetic 18201 18202@geindex Rotate_Left 18203 18204@geindex Rotate_Right 18205 18206In standard Ada, the shift and rotate functions are available only 18207for the predefined modular types in package @code{Interfaces}. However, in 18208GNAT it is possible to define these functions for any integer 18209type (signed or modular), as in this example: 18210 18211@example 18212function Shift_Left 18213 (Value : T; 18214 Amount : Natural) return T; 18215@end example 18216 18217The function name must be one of 18218Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 18219Rotate_Right. T must be an integer type. T'Size must be 182208, 16, 32 or 64 bits; if T is modular, the modulus 18221must be 2**8, 2**16, 2**32 or 2**64. 18222The result type must be the same as the type of @code{Value}. 18223The shift amount must be Natural. 18224The formal parameter names can be anything. 18225 18226A more convenient way of providing these shift operators is to use 18227the Provide_Shift_Operators pragma, which provides the function declarations 18228and corresponding pragma Import's for all five shift functions. 18229 18230@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 18231@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{26e}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{26f} 18232@section Source_Location 18233 18234 18235@geindex Source_Location 18236 18237This intrinsic subprogram is used in the implementation of the 18238library routine @code{GNAT.Source_Info}. The only useful use of the 18239intrinsic import in this case is the one in this unit, so an 18240application program should simply call the function 18241@code{GNAT.Source_Info.Source_Location} to obtain the current 18242source file location. 18243 18244@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 18245@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{270}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{271} 18246@chapter Representation Clauses and Pragmas 18247 18248 18249@geindex Representation Clauses 18250 18251@geindex Representation Clause 18252 18253@geindex Representation Pragma 18254 18255@geindex Pragma 18256@geindex representation 18257 18258This section describes the representation clauses accepted by GNAT, and 18259their effect on the representation of corresponding data objects. 18260 18261GNAT fully implements Annex C (Systems Programming). This means that all 18262the implementation advice sections in chapter 13 are fully implemented. 18263However, these sections only require a minimal level of support for 18264representation clauses. GNAT provides much more extensive capabilities, 18265and this section describes the additional capabilities provided. 18266 18267@menu 18268* Alignment Clauses:: 18269* Size Clauses:: 18270* Storage_Size Clauses:: 18271* Size of Variant Record Objects:: 18272* Biased Representation:: 18273* Value_Size and Object_Size Clauses:: 18274* Component_Size Clauses:: 18275* Bit_Order Clauses:: 18276* Effect of Bit_Order on Byte Ordering:: 18277* Pragma Pack for Arrays:: 18278* Pragma Pack for Records:: 18279* Record Representation Clauses:: 18280* Handling of Records with Holes:: 18281* Enumeration Clauses:: 18282* Address Clauses:: 18283* Use of Address Clauses for Memory-Mapped I/O:: 18284* Effect of Convention on Representation:: 18285* Conventions and Anonymous Access Types:: 18286* Determining the Representations chosen by GNAT:: 18287 18288@end menu 18289 18290@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 18291@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{272}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{273} 18292@section Alignment Clauses 18293 18294 18295@geindex Alignment Clause 18296 18297GNAT requires that all alignment clauses specify a power of 2, and all 18298default alignments are always a power of 2. The default alignment 18299values are as follows: 18300 18301 18302@itemize * 18303 18304@item 18305@emph{Elementary Types}. 18306 18307For elementary types, the alignment is the minimum of the actual size of 18308objects of the type divided by @code{Storage_Unit}, 18309and the maximum alignment supported by the target. 18310(This maximum alignment is given by the GNAT-specific attribute 18311@code{Standard'Maximum_Alignment}; see @ref{18d,,Attribute Maximum_Alignment}.) 18312 18313@geindex Maximum_Alignment attribute 18314 18315For example, for type @code{Long_Float}, the object size is 8 bytes, and the 18316default alignment will be 8 on any target that supports alignments 18317this large, but on some targets, the maximum alignment may be smaller 18318than 8, in which case objects of type @code{Long_Float} will be maximally 18319aligned. 18320 18321@item 18322@emph{Arrays}. 18323 18324For arrays, the alignment is equal to the alignment of the component type 18325for the normal case where no packing or component size is given. If the 18326array is packed, and the packing is effective (see separate section on 18327packed arrays), then the alignment will be either 4, 2, or 1 for long packed 18328arrays or arrays whose length is not known at compile time, depending on 18329whether the component size is divisible by 4, 2, or is odd. For short packed 18330arrays, which are handled internally as modular types, the alignment 18331will be as described for elementary types, e.g. a packed array of length 1833231 bits will have an object size of four bytes, and an alignment of 4. 18333 18334@item 18335@emph{Records}. 18336 18337For the normal unpacked case, the alignment of a record is equal to 18338the maximum alignment of any of its components. For tagged records, this 18339includes the implicit access type used for the tag. If a pragma @code{Pack} 18340is used and all components are packable (see separate section on pragma 18341@code{Pack}), then the resulting alignment is 1, unless the layout of the 18342record makes it profitable to increase it. 18343 18344A special case is when: 18345 18346 18347@itemize * 18348 18349@item 18350the size of the record is given explicitly, or a 18351full record representation clause is given, and 18352 18353@item 18354the size of the record is 2, 4, or 8 bytes. 18355@end itemize 18356 18357In this case, an alignment is chosen to match the 18358size of the record. For example, if we have: 18359 18360@example 18361type Small is record 18362 A, B : Character; 18363end record; 18364for Small'Size use 16; 18365@end example 18366 18367then the default alignment of the record type @code{Small} is 2, not 1. This 18368leads to more efficient code when the record is treated as a unit, and also 18369allows the type to specified as @code{Atomic} on architectures requiring 18370strict alignment. 18371@end itemize 18372 18373An alignment clause may specify a larger alignment than the default value 18374up to some maximum value dependent on the target (obtainable by using the 18375attribute reference @code{Standard'Maximum_Alignment}). It may also specify 18376a smaller alignment than the default value for enumeration, integer and 18377fixed point types, as well as for record types, for example 18378 18379@example 18380type V is record 18381 A : Integer; 18382end record; 18383 18384for V'alignment use 1; 18385@end example 18386 18387@geindex Alignment 18388@geindex default 18389 18390The default alignment for the type @code{V} is 4, as a result of the 18391Integer field in the record, but it is permissible, as shown, to 18392override the default alignment of the record with a smaller value. 18393 18394@geindex Alignment 18395@geindex subtypes 18396 18397Note that according to the Ada standard, an alignment clause applies only 18398to the first named subtype. If additional subtypes are declared, then the 18399compiler is allowed to choose any alignment it likes, and there is no way 18400to control this choice. Consider: 18401 18402@example 18403type R is range 1 .. 10_000; 18404for R'Alignment use 1; 18405subtype RS is R range 1 .. 1000; 18406@end example 18407 18408The alignment clause specifies an alignment of 1 for the first named subtype 18409@code{R} but this does not necessarily apply to @code{RS}. When writing 18410portable Ada code, you should avoid writing code that explicitly or 18411implicitly relies on the alignment of such subtypes. 18412 18413For the GNAT compiler, if an explicit alignment clause is given, this 18414value is also used for any subsequent subtypes. So for GNAT, in the 18415above example, you can count on the alignment of @code{RS} being 1. But this 18416assumption is non-portable, and other compilers may choose different 18417alignments for the subtype @code{RS}. 18418 18419@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 18420@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{274}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{275} 18421@section Size Clauses 18422 18423 18424@geindex Size Clause 18425 18426The default size for a type @code{T} is obtainable through the 18427language-defined attribute @code{T'Size} and also through the 18428equivalent GNAT-defined attribute @code{T'Value_Size}. 18429For objects of type @code{T}, GNAT will generally increase the type size 18430so that the object size (obtainable through the GNAT-defined attribute 18431@code{T'Object_Size}) 18432is a multiple of @code{T'Alignment * Storage_Unit}. 18433 18434For example: 18435 18436@example 18437type Smallint is range 1 .. 6; 18438 18439type Rec is record 18440 Y1 : integer; 18441 Y2 : boolean; 18442end record; 18443@end example 18444 18445In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 18446as specified by the RM rules, 18447but objects of this type will have a size of 8 18448(@code{Smallint'Object_Size} = 8), 18449since objects by default occupy an integral number 18450of storage units. On some targets, notably older 18451versions of the Digital Alpha, the size of stand 18452alone objects of this type may be 32, reflecting 18453the inability of the hardware to do byte load/stores. 18454 18455Similarly, the size of type @code{Rec} is 40 bits 18456(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 18457the alignment is 4, so objects of this type will have 18458their size increased to 64 bits so that it is a multiple 18459of the alignment (in bits). This decision is 18460in accordance with the specific Implementation Advice in RM 13.3(43): 18461 18462@quotation 18463 18464"A @code{Size} clause should be supported for an object if the specified 18465@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 18466to a size in storage elements that is a multiple of the object's 18467@code{Alignment} (if the @code{Alignment} is nonzero)." 18468@end quotation 18469 18470An explicit size clause may be used to override the default size by 18471increasing it. For example, if we have: 18472 18473@example 18474type My_Boolean is new Boolean; 18475for My_Boolean'Size use 32; 18476@end example 18477 18478then values of this type will always be 32 bits long. In the case of 18479discrete types, the size can be increased up to 64 bits, with the effect 18480that the entire specified field is used to hold the value, sign- or 18481zero-extended as appropriate. If more than 64 bits is specified, then 18482padding space is allocated after the value, and a warning is issued that 18483there are unused bits. 18484 18485Similarly the size of records and arrays may be increased, and the effect 18486is to add padding bits after the value. This also causes a warning message 18487to be generated. 18488 18489The largest Size value permitted in GNAT is 2**31-1. Since this is a 18490Size in bits, this corresponds to an object of size 256 megabytes (minus 18491one). This limitation is true on all targets. The reason for this 18492limitation is that it improves the quality of the code in many cases 18493if it is known that a Size value can be accommodated in an object of 18494type Integer. 18495 18496@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 18497@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{276}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{277} 18498@section Storage_Size Clauses 18499 18500 18501@geindex Storage_Size Clause 18502 18503For tasks, the @code{Storage_Size} clause specifies the amount of space 18504to be allocated for the task stack. This cannot be extended, and if the 18505stack is exhausted, then @code{Storage_Error} will be raised (if stack 18506checking is enabled). Use a @code{Storage_Size} attribute definition clause, 18507or a @code{Storage_Size} pragma in the task definition to set the 18508appropriate required size. A useful technique is to include in every 18509task definition a pragma of the form: 18510 18511@example 18512pragma Storage_Size (Default_Stack_Size); 18513@end example 18514 18515Then @code{Default_Stack_Size} can be defined in a global package, and 18516modified as required. Any tasks requiring stack sizes different from the 18517default can have an appropriate alternative reference in the pragma. 18518 18519You can also use the @emph{-d} binder switch to modify the default stack 18520size. 18521 18522For access types, the @code{Storage_Size} clause specifies the maximum 18523space available for allocation of objects of the type. If this space is 18524exceeded then @code{Storage_Error} will be raised by an allocation attempt. 18525In the case where the access type is declared local to a subprogram, the 18526use of a @code{Storage_Size} clause triggers automatic use of a special 18527predefined storage pool (@code{System.Pool_Size}) that ensures that all 18528space for the pool is automatically reclaimed on exit from the scope in 18529which the type is declared. 18530 18531A special case recognized by the compiler is the specification of a 18532@code{Storage_Size} of zero for an access type. This means that no 18533items can be allocated from the pool, and this is recognized at compile 18534time, and all the overhead normally associated with maintaining a fixed 18535size storage pool is eliminated. Consider the following example: 18536 18537@example 18538procedure p is 18539 type R is array (Natural) of Character; 18540 type P is access all R; 18541 for P'Storage_Size use 0; 18542 -- Above access type intended only for interfacing purposes 18543 18544 y : P; 18545 18546 procedure g (m : P); 18547 pragma Import (C, g); 18548 18549 -- ... 18550 18551begin 18552 -- ... 18553 y := new R; 18554end; 18555@end example 18556 18557As indicated in this example, these dummy storage pools are often useful in 18558connection with interfacing where no object will ever be allocated. If you 18559compile the above example, you get the warning: 18560 18561@example 18562p.adb:16:09: warning: allocation from empty storage pool 18563p.adb:16:09: warning: Storage_Error will be raised at run time 18564@end example 18565 18566Of course in practice, there will not be any explicit allocators in the 18567case of such an access declaration. 18568 18569@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 18570@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{279} 18571@section Size of Variant Record Objects 18572 18573 18574@geindex Size 18575@geindex variant record objects 18576 18577@geindex Variant record objects 18578@geindex size 18579 18580In the case of variant record objects, there is a question whether Size gives 18581information about a particular variant, or the maximum size required 18582for any variant. Consider the following program 18583 18584@example 18585with Text_IO; use Text_IO; 18586procedure q is 18587 type R1 (A : Boolean := False) is record 18588 case A is 18589 when True => X : Character; 18590 when False => null; 18591 end case; 18592 end record; 18593 18594 V1 : R1 (False); 18595 V2 : R1; 18596 18597begin 18598 Put_Line (Integer'Image (V1'Size)); 18599 Put_Line (Integer'Image (V2'Size)); 18600end q; 18601@end example 18602 18603Here we are dealing with a variant record, where the True variant 18604requires 16 bits, and the False variant requires 8 bits. 18605In the above example, both V1 and V2 contain the False variant, 18606which is only 8 bits long. However, the result of running the 18607program is: 18608 18609@example 186108 1861116 18612@end example 18613 18614The reason for the difference here is that the discriminant value of 18615V1 is fixed, and will always be False. It is not possible to assign 18616a True variant value to V1, therefore 8 bits is sufficient. On the 18617other hand, in the case of V2, the initial discriminant value is 18618False (from the default), but it is possible to assign a True 18619variant value to V2, therefore 16 bits must be allocated for V2 18620in the general case, even fewer bits may be needed at any particular 18621point during the program execution. 18622 18623As can be seen from the output of this program, the @code{'Size} 18624attribute applied to such an object in GNAT gives the actual allocated 18625size of the variable, which is the largest size of any of the variants. 18626The Ada Reference Manual is not completely clear on what choice should 18627be made here, but the GNAT behavior seems most consistent with the 18628language in the RM. 18629 18630In some cases, it may be desirable to obtain the size of the current 18631variant, rather than the size of the largest variant. This can be 18632achieved in GNAT by making use of the fact that in the case of a 18633subprogram parameter, GNAT does indeed return the size of the current 18634variant (because a subprogram has no way of knowing how much space 18635is actually allocated for the actual). 18636 18637Consider the following modified version of the above program: 18638 18639@example 18640with Text_IO; use Text_IO; 18641procedure q is 18642 type R1 (A : Boolean := False) is record 18643 case A is 18644 when True => X : Character; 18645 when False => null; 18646 end case; 18647 end record; 18648 18649 V2 : R1; 18650 18651 function Size (V : R1) return Integer is 18652 begin 18653 return V'Size; 18654 end Size; 18655 18656begin 18657 Put_Line (Integer'Image (V2'Size)); 18658 Put_Line (Integer'Image (Size (V2))); 18659 V2 := (True, 'x'); 18660 Put_Line (Integer'Image (V2'Size)); 18661 Put_Line (Integer'Image (Size (V2))); 18662end q; 18663@end example 18664 18665The output from this program is 18666 18667@example 1866816 186698 1867016 1867116 18672@end example 18673 18674Here we see that while the @code{'Size} attribute always returns 18675the maximum size, regardless of the current variant value, the 18676@code{Size} function does indeed return the size of the current 18677variant value. 18678 18679@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18680@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{27a}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{27b} 18681@section Biased Representation 18682 18683 18684@geindex Size for biased representation 18685 18686@geindex Biased representation 18687 18688In the case of scalars with a range starting at other than zero, it is 18689possible in some cases to specify a size smaller than the default minimum 18690value, and in such cases, GNAT uses an unsigned biased representation, 18691in which zero is used to represent the lower bound, and successive values 18692represent successive values of the type. 18693 18694For example, suppose we have the declaration: 18695 18696@example 18697type Small is range -7 .. -4; 18698for Small'Size use 2; 18699@end example 18700 18701Although the default size of type @code{Small} is 4, the @code{Size} 18702clause is accepted by GNAT and results in the following representation 18703scheme: 18704 18705@example 18706-7 is represented as 2#00# 18707-6 is represented as 2#01# 18708-5 is represented as 2#10# 18709-4 is represented as 2#11# 18710@end example 18711 18712Biased representation is only used if the specified @code{Size} clause 18713cannot be accepted in any other manner. These reduced sizes that force 18714biased representation can be used for all discrete types except for 18715enumeration types for which a representation clause is given. 18716 18717@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18718@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{27c}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{27d} 18719@section Value_Size and Object_Size Clauses 18720 18721 18722@geindex Value_Size 18723 18724@geindex Object_Size 18725 18726@geindex Size 18727@geindex of objects 18728 18729In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 18730number of bits required to hold values of type @code{T}. 18731Although this interpretation was allowed in Ada 83, it was not required, 18732and this requirement in practice can cause some significant difficulties. 18733For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 18734However, in Ada 95 and Ada 2005, 18735@code{Natural'Size} is 18736typically 31. This means that code may change in behavior when moving 18737from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18738 18739@example 18740type Rec is record; 18741 A : Natural; 18742 B : Natural; 18743end record; 18744 18745for Rec use record 18746 at 0 range 0 .. Natural'Size - 1; 18747 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18748end record; 18749@end example 18750 18751In the above code, since the typical size of @code{Natural} objects 18752is 32 bits and @code{Natural'Size} is 31, the above code can cause 18753unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18754there are cases where the fact that the object size can exceed the 18755size of the type causes surprises. 18756 18757To help get around this problem GNAT provides two implementation 18758defined attributes, @code{Value_Size} and @code{Object_Size}. When 18759applied to a type, these attributes yield the size of the type 18760(corresponding to the RM defined size attribute), and the size of 18761objects of the type respectively. 18762 18763The @code{Object_Size} is used for determining the default size of 18764objects and components. This size value can be referred to using the 18765@code{Object_Size} attribute. The phrase 'is used' here means that it is 18766the basis of the determination of the size. The backend is free to 18767pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18768character might be stored in 32 bits on a machine with no efficient 18769byte access instructions such as the Alpha. 18770 18771The default rules for the value of @code{Object_Size} for 18772discrete types are as follows: 18773 18774 18775@itemize * 18776 18777@item 18778The @code{Object_Size} for base subtypes reflect the natural hardware 18779size in bits (run the compiler with @emph{-gnatS} to find those values 18780for numeric types). Enumeration types and fixed-point base subtypes have 187818, 16, 32, or 64 bits for this size, depending on the range of values 18782to be stored. 18783 18784@item 18785The @code{Object_Size} of a subtype is the same as the 18786@code{Object_Size} of 18787the type from which it is obtained. 18788 18789@item 18790The @code{Object_Size} of a derived base type is copied from the parent 18791base type, and the @code{Object_Size} of a derived first subtype is copied 18792from the parent first subtype. 18793@end itemize 18794 18795The @code{Value_Size} attribute 18796is the (minimum) number of bits required to store a value 18797of the type. 18798This value is used to determine how tightly to pack 18799records or arrays with components of this type, and also affects 18800the semantics of unchecked conversion (unchecked conversions where 18801the @code{Value_Size} values differ generate a warning, and are potentially 18802target dependent). 18803 18804The default rules for the value of @code{Value_Size} are as follows: 18805 18806 18807@itemize * 18808 18809@item 18810The @code{Value_Size} for a base subtype is the minimum number of bits 18811required to store all values of the type (including the sign bit 18812only if negative values are possible). 18813 18814@item 18815If a subtype statically matches the first subtype of a given type, then it has 18816by default the same @code{Value_Size} as the first subtype. This is a 18817consequence of RM 13.1(14): "if two subtypes statically match, 18818then their subtype-specific aspects are the same".) 18819 18820@item 18821All other subtypes have a @code{Value_Size} corresponding to the minimum 18822number of bits required to store all values of the subtype. For 18823dynamic bounds, it is assumed that the value can range down or up 18824to the corresponding bound of the ancestor 18825@end itemize 18826 18827The RM defined attribute @code{Size} corresponds to the 18828@code{Value_Size} attribute. 18829 18830The @code{Size} attribute may be defined for a first-named subtype. This sets 18831the @code{Value_Size} of 18832the first-named subtype to the given value, and the 18833@code{Object_Size} of this first-named subtype to the given value padded up 18834to an appropriate boundary. It is a consequence of the default rules 18835above that this @code{Object_Size} will apply to all further subtypes. On the 18836other hand, @code{Value_Size} is affected only for the first subtype, any 18837dynamic subtypes obtained from it directly, and any statically matching 18838subtypes. The @code{Value_Size} of any other static subtypes is not affected. 18839 18840@code{Value_Size} and 18841@code{Object_Size} may be explicitly set for any subtype using 18842an attribute definition clause. Note that the use of these attributes 18843can cause the RM 13.1(14) rule to be violated. If two access types 18844reference aliased objects whose subtypes have differing @code{Object_Size} 18845values as a result of explicit attribute definition clauses, then it 18846is illegal to convert from one access subtype to the other. For a more 18847complete description of this additional legality rule, see the 18848description of the @code{Object_Size} attribute. 18849 18850To get a feel for the difference, consider the following examples (note 18851that in each case the base is @code{Short_Short_Integer} with a size of 8): 18852 18853 18854@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 18855@headitem 18856 18857Type or subtype declaration 18858 18859@tab 18860 18861Object_Size 18862 18863@tab 18864 18865Value_Size 18866 18867@item 18868 18869@code{type x1 is range 0 .. 5;} 18870 18871@tab 18872 188738 18874 18875@tab 18876 188773 18878 18879@item 18880 18881@code{type x2 is range 0 .. 5;} 18882@code{for x2'size use 12;} 18883 18884@tab 18885 1888616 18887 18888@tab 18889 1889012 18891 18892@item 18893 18894@code{subtype x3 is x2 range 0 .. 3;} 18895 18896@tab 18897 1889816 18899 18900@tab 18901 189022 18903 18904@item 18905 18906@code{subtype x4 is x2'base range 0 .. 10;} 18907 18908@tab 18909 189108 18911 18912@tab 18913 189144 18915 18916@item 18917 18918@code{dynamic : x2'Base range -64 .. +63;} 18919 18920@tab 18921 18922@tab 18923 18924@item 18925 18926@code{subtype x5 is x2 range 0 .. dynamic;} 18927 18928@tab 18929 1893016 18931 18932@tab 18933 189343* 18935 18936@item 18937 18938@code{subtype x6 is x2'base range 0 .. dynamic;} 18939 18940@tab 18941 189428 18943 18944@tab 18945 189467* 18947 18948@end multitable 18949 18950 18951Note: the entries marked '*' are not actually specified by the Ada 18952Reference Manual, which has nothing to say about size in the dynamic 18953case. What GNAT does is to allocate sufficient bits to accomodate any 18954possible dynamic values for the bounds at run-time. 18955 18956So far, so good, but GNAT has to obey the RM rules, so the question is 18957under what conditions must the RM @code{Size} be used. 18958The following is a list 18959of the occasions on which the RM @code{Size} must be used: 18960 18961 18962@itemize * 18963 18964@item 18965Component size for packed arrays or records 18966 18967@item 18968Value of the attribute @code{Size} for a type 18969 18970@item 18971Warning about sizes not matching for unchecked conversion 18972@end itemize 18973 18974For record types, the @code{Object_Size} is always a multiple of the 18975alignment of the type (this is true for all types). In some cases the 18976@code{Value_Size} can be smaller. Consider: 18977 18978@example 18979type R is record 18980 X : Integer; 18981 Y : Character; 18982end record; 18983@end example 18984 18985On a typical 32-bit architecture, the X component will be four bytes, and 18986require four-byte alignment, and the Y component will be one byte. In this 18987case @code{R'Value_Size} will be 40 (bits) since this is the minimum size 18988required to store a value of this type, and for example, it is permissible 18989to have a component of type R in an outer array whose component size is 18990specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), 18991since it must be rounded up so that this value is a multiple of the 18992alignment (4 bytes = 32 bits). 18993 18994For all other types, the @code{Object_Size} 18995and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). 18996Only @code{Size} may be specified for such types. 18997 18998Note that @code{Value_Size} can be used to force biased representation 18999for a particular subtype. Consider this example: 19000 19001@example 19002type R is (A, B, C, D, E, F); 19003subtype RAB is R range A .. B; 19004subtype REF is R range E .. F; 19005@end example 19006 19007By default, @code{RAB} 19008has a size of 1 (sufficient to accommodate the representation 19009of @code{A} and @code{B}, 0 and 1), and @code{REF} 19010has a size of 3 (sufficient to accommodate the representation 19011of @code{E} and @code{F}, 4 and 5). But if we add the 19012following @code{Value_Size} attribute definition clause: 19013 19014@example 19015for REF'Value_Size use 1; 19016@end example 19017 19018then biased representation is forced for @code{REF}, 19019and 0 will represent @code{E} and 1 will represent @code{F}. 19020A warning is issued when a @code{Value_Size} attribute 19021definition clause forces biased representation. This 19022warning can be turned off using @code{-gnatw.B}. 19023 19024@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 19025@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{27e}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{27f} 19026@section Component_Size Clauses 19027 19028 19029@geindex Component_Size Clause 19030 19031Normally, the value specified in a component size clause must be consistent 19032with the subtype of the array component with regard to size and alignment. 19033In other words, the value specified must be at least equal to the size 19034of this subtype, and must be a multiple of the alignment value. 19035 19036In addition, component size clauses are allowed which cause the array 19037to be packed, by specifying a smaller value. A first case is for 19038component size values in the range 1 through 63. The value specified 19039must not be smaller than the Size of the subtype. GNAT will accurately 19040honor all packing requests in this range. For example, if we have: 19041 19042@example 19043type r is array (1 .. 8) of Natural; 19044for r'Component_Size use 31; 19045@end example 19046 19047then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 19048Of course access to the components of such an array is considerably 19049less efficient than if the natural component size of 32 is used. 19050A second case is when the subtype of the component is a record type 19051padded because of its default alignment. For example, if we have: 19052 19053@example 19054type r is record 19055 i : Integer; 19056 j : Integer; 19057 b : Boolean; 19058end record; 19059 19060type a is array (1 .. 8) of r; 19061for a'Component_Size use 72; 19062@end example 19063 19064then the resulting array has a length of 72 bytes, instead of 96 bytes 19065if the alignment of the record (4) was obeyed. 19066 19067Note that there is no point in giving both a component size clause 19068and a pragma Pack for the same array type. if such duplicate 19069clauses are given, the pragma Pack will be ignored. 19070 19071@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 19072@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{280}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{281} 19073@section Bit_Order Clauses 19074 19075 19076@geindex Bit_Order Clause 19077 19078@geindex bit ordering 19079 19080@geindex ordering 19081@geindex of bits 19082 19083For record subtypes, GNAT permits the specification of the @code{Bit_Order} 19084attribute. The specification may either correspond to the default bit 19085order for the target, in which case the specification has no effect and 19086places no additional restrictions, or it may be for the non-standard 19087setting (that is the opposite of the default). 19088 19089In the case where the non-standard value is specified, the effect is 19090to renumber bits within each byte, but the ordering of bytes is not 19091affected. There are certain 19092restrictions placed on component clauses as follows: 19093 19094 19095@itemize * 19096 19097@item 19098Components fitting within a single storage unit. 19099 19100These are unrestricted, and the effect is merely to renumber bits. For 19101example if we are on a little-endian machine with @code{Low_Order_First} 19102being the default, then the following two declarations have exactly 19103the same effect: 19104 19105@example 19106type R1 is record 19107 A : Boolean; 19108 B : Integer range 1 .. 120; 19109end record; 19110 19111for R1 use record 19112 A at 0 range 0 .. 0; 19113 B at 0 range 1 .. 7; 19114end record; 19115 19116type R2 is record 19117 A : Boolean; 19118 B : Integer range 1 .. 120; 19119end record; 19120 19121for R2'Bit_Order use High_Order_First; 19122 19123for R2 use record 19124 A at 0 range 7 .. 7; 19125 B at 0 range 0 .. 6; 19126end record; 19127@end example 19128 19129The useful application here is to write the second declaration with the 19130@code{Bit_Order} attribute definition clause, and know that it will be treated 19131the same, regardless of whether the target is little-endian or big-endian. 19132 19133@item 19134Components occupying an integral number of bytes. 19135 19136These are components that exactly fit in two or more bytes. Such component 19137declarations are allowed, but have no effect, since it is important to realize 19138that the @code{Bit_Order} specification does not affect the ordering of bytes. 19139In particular, the following attempt at getting an endian-independent integer 19140does not work: 19141 19142@example 19143type R2 is record 19144 A : Integer; 19145end record; 19146 19147for R2'Bit_Order use High_Order_First; 19148 19149for R2 use record 19150 A at 0 range 0 .. 31; 19151end record; 19152@end example 19153 19154This declaration will result in a little-endian integer on a 19155little-endian machine, and a big-endian integer on a big-endian machine. 19156If byte flipping is required for interoperability between big- and 19157little-endian machines, this must be explicitly programmed. This capability 19158is not provided by @code{Bit_Order}. 19159 19160@item 19161Components that are positioned across byte boundaries. 19162 19163but do not occupy an integral number of bytes. Given that bytes are not 19164reordered, such fields would occupy a non-contiguous sequence of bits 19165in memory, requiring non-trivial code to reassemble. They are for this 19166reason not permitted, and any component clause specifying such a layout 19167will be flagged as illegal by GNAT. 19168@end itemize 19169 19170Since the misconception that Bit_Order automatically deals with all 19171endian-related incompatibilities is a common one, the specification of 19172a component field that is an integral number of bytes will always 19173generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} 19174if desired. The following section contains additional 19175details regarding the issue of byte ordering. 19176 19177@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 19178@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{282}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{283} 19179@section Effect of Bit_Order on Byte Ordering 19180 19181 19182@geindex byte ordering 19183 19184@geindex ordering 19185@geindex of bytes 19186 19187In this section we will review the effect of the @code{Bit_Order} attribute 19188definition clause on byte ordering. Briefly, it has no effect at all, but 19189a detailed example will be helpful. Before giving this 19190example, let us review the precise 19191definition of the effect of defining @code{Bit_Order}. The effect of a 19192non-standard bit order is described in section 13.5.3 of the Ada 19193Reference Manual: 19194 19195@quotation 19196 19197"2 A bit ordering is a method of interpreting the meaning of 19198the storage place attributes." 19199@end quotation 19200 19201To understand the precise definition of storage place attributes in 19202this context, we visit section 13.5.1 of the manual: 19203 19204@quotation 19205 19206"13 A record_representation_clause (without the mod_clause) 19207specifies the layout. The storage place attributes (see 13.5.2) 19208are taken from the values of the position, first_bit, and last_bit 19209expressions after normalizing those values so that first_bit is 19210less than Storage_Unit." 19211@end quotation 19212 19213The critical point here is that storage places are taken from 19214the values after normalization, not before. So the @code{Bit_Order} 19215interpretation applies to normalized values. The interpretation 19216is described in the later part of the 13.5.3 paragraph: 19217 19218@quotation 19219 19220"2 A bit ordering is a method of interpreting the meaning of 19221the storage place attributes. High_Order_First (known in the 19222vernacular as 'big endian') means that the first bit of a 19223storage element (bit 0) is the most significant bit (interpreting 19224the sequence of bits that represent a component as an unsigned 19225integer value). Low_Order_First (known in the vernacular as 19226'little endian') means the opposite: the first bit is the 19227least significant." 19228@end quotation 19229 19230Note that the numbering is with respect to the bits of a storage 19231unit. In other words, the specification affects only the numbering 19232of bits within a single storage unit. 19233 19234We can make the effect clearer by giving an example. 19235 19236Suppose that we have an external device which presents two bytes, the first 19237byte presented, which is the first (low addressed byte) of the two byte 19238record is called Master, and the second byte is called Slave. 19239 19240The left most (most significant bit is called Control for each byte, and 19241the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost 19242(least significant) bit. 19243 19244On a big-endian machine, we can write the following representation clause 19245 19246@example 19247type Data is record 19248 Master_Control : Bit; 19249 Master_V1 : Bit; 19250 Master_V2 : Bit; 19251 Master_V3 : Bit; 19252 Master_V4 : Bit; 19253 Master_V5 : Bit; 19254 Master_V6 : Bit; 19255 Master_V7 : Bit; 19256 Slave_Control : Bit; 19257 Slave_V1 : Bit; 19258 Slave_V2 : Bit; 19259 Slave_V3 : Bit; 19260 Slave_V4 : Bit; 19261 Slave_V5 : Bit; 19262 Slave_V6 : Bit; 19263 Slave_V7 : Bit; 19264end record; 19265 19266for Data use record 19267 Master_Control at 0 range 0 .. 0; 19268 Master_V1 at 0 range 1 .. 1; 19269 Master_V2 at 0 range 2 .. 2; 19270 Master_V3 at 0 range 3 .. 3; 19271 Master_V4 at 0 range 4 .. 4; 19272 Master_V5 at 0 range 5 .. 5; 19273 Master_V6 at 0 range 6 .. 6; 19274 Master_V7 at 0 range 7 .. 7; 19275 Slave_Control at 1 range 0 .. 0; 19276 Slave_V1 at 1 range 1 .. 1; 19277 Slave_V2 at 1 range 2 .. 2; 19278 Slave_V3 at 1 range 3 .. 3; 19279 Slave_V4 at 1 range 4 .. 4; 19280 Slave_V5 at 1 range 5 .. 5; 19281 Slave_V6 at 1 range 6 .. 6; 19282 Slave_V7 at 1 range 7 .. 7; 19283end record; 19284@end example 19285 19286Now if we move this to a little endian machine, then the bit ordering within 19287the byte is backwards, so we have to rewrite the record rep clause as: 19288 19289@example 19290for Data use record 19291 Master_Control at 0 range 7 .. 7; 19292 Master_V1 at 0 range 6 .. 6; 19293 Master_V2 at 0 range 5 .. 5; 19294 Master_V3 at 0 range 4 .. 4; 19295 Master_V4 at 0 range 3 .. 3; 19296 Master_V5 at 0 range 2 .. 2; 19297 Master_V6 at 0 range 1 .. 1; 19298 Master_V7 at 0 range 0 .. 0; 19299 Slave_Control at 1 range 7 .. 7; 19300 Slave_V1 at 1 range 6 .. 6; 19301 Slave_V2 at 1 range 5 .. 5; 19302 Slave_V3 at 1 range 4 .. 4; 19303 Slave_V4 at 1 range 3 .. 3; 19304 Slave_V5 at 1 range 2 .. 2; 19305 Slave_V6 at 1 range 1 .. 1; 19306 Slave_V7 at 1 range 0 .. 0; 19307end record; 19308@end example 19309 19310It is a nuisance to have to rewrite the clause, especially if 19311the code has to be maintained on both machines. However, 19312this is a case that we can handle with the 19313@code{Bit_Order} attribute if it is implemented. 19314Note that the implementation is not required on byte addressed 19315machines, but it is indeed implemented in GNAT. 19316This means that we can simply use the 19317first record clause, together with the declaration 19318 19319@example 19320for Data'Bit_Order use High_Order_First; 19321@end example 19322 19323and the effect is what is desired, namely the layout is exactly the same, 19324independent of whether the code is compiled on a big-endian or little-endian 19325machine. 19326 19327The important point to understand is that byte ordering is not affected. 19328A @code{Bit_Order} attribute definition never affects which byte a field 19329ends up in, only where it ends up in that byte. 19330To make this clear, let us rewrite the record rep clause of the previous 19331example as: 19332 19333@example 19334for Data'Bit_Order use High_Order_First; 19335for Data use record 19336 Master_Control at 0 range 0 .. 0; 19337 Master_V1 at 0 range 1 .. 1; 19338 Master_V2 at 0 range 2 .. 2; 19339 Master_V3 at 0 range 3 .. 3; 19340 Master_V4 at 0 range 4 .. 4; 19341 Master_V5 at 0 range 5 .. 5; 19342 Master_V6 at 0 range 6 .. 6; 19343 Master_V7 at 0 range 7 .. 7; 19344 Slave_Control at 0 range 8 .. 8; 19345 Slave_V1 at 0 range 9 .. 9; 19346 Slave_V2 at 0 range 10 .. 10; 19347 Slave_V3 at 0 range 11 .. 11; 19348 Slave_V4 at 0 range 12 .. 12; 19349 Slave_V5 at 0 range 13 .. 13; 19350 Slave_V6 at 0 range 14 .. 14; 19351 Slave_V7 at 0 range 15 .. 15; 19352end record; 19353@end example 19354 19355This is exactly equivalent to saying (a repeat of the first example): 19356 19357@example 19358for Data'Bit_Order use High_Order_First; 19359for Data use record 19360 Master_Control at 0 range 0 .. 0; 19361 Master_V1 at 0 range 1 .. 1; 19362 Master_V2 at 0 range 2 .. 2; 19363 Master_V3 at 0 range 3 .. 3; 19364 Master_V4 at 0 range 4 .. 4; 19365 Master_V5 at 0 range 5 .. 5; 19366 Master_V6 at 0 range 6 .. 6; 19367 Master_V7 at 0 range 7 .. 7; 19368 Slave_Control at 1 range 0 .. 0; 19369 Slave_V1 at 1 range 1 .. 1; 19370 Slave_V2 at 1 range 2 .. 2; 19371 Slave_V3 at 1 range 3 .. 3; 19372 Slave_V4 at 1 range 4 .. 4; 19373 Slave_V5 at 1 range 5 .. 5; 19374 Slave_V6 at 1 range 6 .. 6; 19375 Slave_V7 at 1 range 7 .. 7; 19376end record; 19377@end example 19378 19379Why are they equivalent? Well take a specific field, the @code{Slave_V2} 19380field. The storage place attributes are obtained by normalizing the 19381values given so that the @code{First_Bit} value is less than 8. After 19382normalizing the values (0,10,10) we get (1,2,2) which is exactly what 19383we specified in the other case. 19384 19385Now one might expect that the @code{Bit_Order} attribute might affect 19386bit numbering within the entire record component (two bytes in this 19387case, thus affecting which byte fields end up in), but that is not 19388the way this feature is defined, it only affects numbering of bits, 19389not which byte they end up in. 19390 19391Consequently it never makes sense to specify a starting bit number 19392greater than 7 (for a byte addressable field) if an attribute 19393definition for @code{Bit_Order} has been given, and indeed it 19394may be actively confusing to specify such a value, so the compiler 19395generates a warning for such usage. 19396 19397If you do need to control byte ordering then appropriate conditional 19398values must be used. If in our example, the slave byte came first on 19399some machines we might write: 19400 19401@example 19402Master_Byte_First constant Boolean := ...; 19403 19404Master_Byte : constant Natural := 19405 1 - Boolean'Pos (Master_Byte_First); 19406Slave_Byte : constant Natural := 19407 Boolean'Pos (Master_Byte_First); 19408 19409for Data'Bit_Order use High_Order_First; 19410for Data use record 19411 Master_Control at Master_Byte range 0 .. 0; 19412 Master_V1 at Master_Byte range 1 .. 1; 19413 Master_V2 at Master_Byte range 2 .. 2; 19414 Master_V3 at Master_Byte range 3 .. 3; 19415 Master_V4 at Master_Byte range 4 .. 4; 19416 Master_V5 at Master_Byte range 5 .. 5; 19417 Master_V6 at Master_Byte range 6 .. 6; 19418 Master_V7 at Master_Byte range 7 .. 7; 19419 Slave_Control at Slave_Byte range 0 .. 0; 19420 Slave_V1 at Slave_Byte range 1 .. 1; 19421 Slave_V2 at Slave_Byte range 2 .. 2; 19422 Slave_V3 at Slave_Byte range 3 .. 3; 19423 Slave_V4 at Slave_Byte range 4 .. 4; 19424 Slave_V5 at Slave_Byte range 5 .. 5; 19425 Slave_V6 at Slave_Byte range 6 .. 6; 19426 Slave_V7 at Slave_Byte range 7 .. 7; 19427end record; 19428@end example 19429 19430Now to switch between machines, all that is necessary is 19431to set the boolean constant @code{Master_Byte_First} in 19432an appropriate manner. 19433 19434@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 19435@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{285} 19436@section Pragma Pack for Arrays 19437 19438 19439@geindex Pragma Pack (for arrays) 19440 19441Pragma @code{Pack} applied to an array has an effect that depends upon whether the 19442component type is @emph{packable}. For a component type to be @emph{packable}, it must 19443be one of the following cases: 19444 19445 19446@itemize * 19447 19448@item 19449Any elementary type. 19450 19451@item 19452Any small packed array type with a static size. 19453 19454@item 19455Any small simple record type with a static size. 19456@end itemize 19457 19458For all these cases, if the component subtype size is in the range 194591 through 64, then the effect of the pragma @code{Pack} is exactly as though a 19460component size were specified giving the component subtype size. 19461 19462All other types are non-packable, they occupy an integral number of storage 19463units and the only effect of pragma Pack is to remove alignment gaps. 19464 19465For example if we have: 19466 19467@example 19468type r is range 0 .. 17; 19469 19470type ar is array (1 .. 8) of r; 19471pragma Pack (ar); 19472@end example 19473 19474Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, 19475and the size of the array @code{ar} will be exactly 40 bits). 19476 19477Note that in some cases this rather fierce approach to packing can produce 19478unexpected effects. For example, in Ada 95 and Ada 2005, 19479subtype @code{Natural} typically has a size of 31, meaning that if you 19480pack an array of @code{Natural}, you get 31-bit 19481close packing, which saves a few bits, but results in far less efficient 19482access. Since many other Ada compilers will ignore such a packing request, 19483GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 19484might not be what is intended. You can easily remove this warning by 19485using an explicit @code{Component_Size} setting instead, which never generates 19486a warning, since the intention of the programmer is clear in this case. 19487 19488GNAT treats packed arrays in one of two ways. If the size of the array is 19489known at compile time and is less than 64 bits, then internally the array 19490is represented as a single modular type, of exactly the appropriate number 19491of bits. If the length is greater than 63 bits, or is not known at compile 19492time, then the packed array is represented as an array of bytes, and the 19493length is always a multiple of 8 bits. 19494 19495Note that to represent a packed array as a modular type, the alignment must 19496be suitable for the modular type involved. For example, on typical machines 19497a 32-bit packed array will be represented by a 32-bit modular integer with 19498an alignment of four bytes. If you explicitly override the default alignment 19499with an alignment clause that is too small, the modular representation 19500cannot be used. For example, consider the following set of declarations: 19501 19502@example 19503type R is range 1 .. 3; 19504type S is array (1 .. 31) of R; 19505for S'Component_Size use 2; 19506for S'Size use 62; 19507for S'Alignment use 1; 19508@end example 19509 19510If the alignment clause were not present, then a 62-bit modular 19511representation would be chosen (typically with an alignment of 4 or 8 19512bytes depending on the target). But the default alignment is overridden 19513with the explicit alignment clause. This means that the modular 19514representation cannot be used, and instead the array of bytes 19515representation must be used, meaning that the length must be a multiple 19516of 8. Thus the above set of declarations will result in a diagnostic 19517rejecting the size clause and noting that the minimum size allowed is 64. 19518 19519@geindex Pragma Pack (for type Natural) 19520 19521@geindex Pragma Pack warning 19522 19523One special case that is worth noting occurs when the base type of the 19524component size is 8/16/32 and the subtype is one bit less. Notably this 19525occurs with subtype @code{Natural}. Consider: 19526 19527@example 19528type Arr is array (1 .. 32) of Natural; 19529pragma Pack (Arr); 19530@end example 19531 19532In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 19533since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 19534Ada 83 compilers did not attempt 31 bit packing. 19535 19536In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 19537GNAT really does pack 31-bit subtype to 31 bits. This may result in a 19538substantial unintended performance penalty when porting legacy Ada 83 code. 19539To help prevent this, GNAT generates a warning in such cases. If you really 19540want 31 bit packing in a case like this, you can set the component size 19541explicitly: 19542 19543@example 19544type Arr is array (1 .. 32) of Natural; 19545for Arr'Component_Size use 31; 19546@end example 19547 19548Here 31-bit packing is achieved as required, and no warning is generated, 19549since in this case the programmer intention is clear. 19550 19551@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 19552@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{286}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{287} 19553@section Pragma Pack for Records 19554 19555 19556@geindex Pragma Pack (for records) 19557 19558Pragma @code{Pack} applied to a record will pack the components to reduce 19559wasted space from alignment gaps and by reducing the amount of space 19560taken by components. We distinguish between @emph{packable} components and 19561@emph{non-packable} components. 19562Components of the following types are considered packable: 19563 19564 19565@itemize * 19566 19567@item 19568Components of an elementary type are packable unless they are aliased, 19569independent, or of an atomic type. 19570 19571@item 19572Small packed arrays, where the size is statically known, are represented 19573internally as modular integers, and so they are also packable. 19574 19575@item 19576Small simple records, where the size is statically known, are also packable. 19577@end itemize 19578 19579For all these cases, if the @code{'Size} value is in the range 1 through 64, the 19580components occupy the exact number of bits corresponding to this value 19581and are packed with no padding bits, i.e. they can start on an arbitrary 19582bit boundary. 19583 19584All other types are non-packable, they occupy an integral number of storage 19585units and the only effect of pragma @code{Pack} is to remove alignment gaps. 19586 19587For example, consider the record 19588 19589@example 19590type Rb1 is array (1 .. 13) of Boolean; 19591pragma Pack (Rb1); 19592 19593type Rb2 is array (1 .. 65) of Boolean; 19594pragma Pack (Rb2); 19595 19596type AF is new Float with Atomic; 19597 19598type X2 is record 19599 L1 : Boolean; 19600 L2 : Duration; 19601 L3 : AF; 19602 L4 : Boolean; 19603 L5 : Rb1; 19604 L6 : Rb2; 19605end record; 19606pragma Pack (X2); 19607@end example 19608 19609The representation for the record @code{X2} is as follows: 19610 19611@example 19612for X2'Size use 224; 19613for X2 use record 19614 L1 at 0 range 0 .. 0; 19615 L2 at 0 range 1 .. 64; 19616 L3 at 12 range 0 .. 31; 19617 L4 at 16 range 0 .. 0; 19618 L5 at 16 range 1 .. 13; 19619 L6 at 18 range 0 .. 71; 19620end record; 19621@end example 19622 19623Studying this example, we see that the packable fields @code{L1} 19624and @code{L2} are 19625of length equal to their sizes, and placed at specific bit boundaries (and 19626not byte boundaries) to 19627eliminate padding. But @code{L3} is of a non-packable float type (because 19628it is aliased), so it is on the next appropriate alignment boundary. 19629 19630The next two fields are fully packable, so @code{L4} and @code{L5} are 19631minimally packed with no gaps. However, type @code{Rb2} is a packed 19632array that is longer than 64 bits, so it is itself non-packable. Thus 19633the @code{L6} field is aligned to the next byte boundary, and takes an 19634integral number of bytes, i.e., 72 bits. 19635 19636@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19637@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{288}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{289} 19638@section Record Representation Clauses 19639 19640 19641@geindex Record Representation Clause 19642 19643Record representation clauses may be given for all record types, including 19644types obtained by record extension. Component clauses are allowed for any 19645static component. The restrictions on component clauses depend on the type 19646of the component. 19647 19648@geindex Component Clause 19649 19650For all components of an elementary type, the only restriction on component 19651clauses is that the size must be at least the @code{'Size} value of the type 19652(actually the Value_Size). There are no restrictions due to alignment, 19653and such components may freely cross storage boundaries. 19654 19655Packed arrays with a size up to and including 64 bits are represented 19656internally using a modular type with the appropriate number of bits, and 19657thus the same lack of restriction applies. For example, if you declare: 19658 19659@example 19660type R is array (1 .. 49) of Boolean; 19661pragma Pack (R); 19662for R'Size use 49; 19663@end example 19664 19665then a component clause for a component of type @code{R} may start on any 19666specified bit boundary, and may specify a value of 49 bits or greater. 19667 19668For packed bit arrays that are longer than 64 bits, there are two 19669cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 19670including the important case of single bits or boolean values, then 19671there are no limitations on placement of such components, and they 19672may start and end at arbitrary bit boundaries. 19673 19674If the component size is not a power of 2 (e.g., 3 or 5), then 19675an array of this type longer than 64 bits must always be placed on 19676on a storage unit (byte) boundary and occupy an integral number 19677of storage units (bytes). Any component clause that does not 19678meet this requirement will be rejected. 19679 19680Any aliased component, or component of an aliased type, must 19681have its normal alignment and size. A component clause that 19682does not meet this requirement will be rejected. 19683 19684The tag field of a tagged type always occupies an address sized field at 19685the start of the record. No component clause may attempt to overlay this 19686tag. When a tagged type appears as a component, the tag field must have 19687proper alignment 19688 19689In the case of a record extension @code{T1}, of a type @code{T}, no component clause applied 19690to the type @code{T1} can specify a storage location that would overlap the first 19691@code{T'Size} bytes of the record. 19692 19693For all other component types, including non-bit-packed arrays, 19694the component can be placed at an arbitrary bit boundary, 19695so for example, the following is permitted: 19696 19697@example 19698type R is array (1 .. 10) of Boolean; 19699for R'Size use 80; 19700 19701type Q is record 19702 G, H : Boolean; 19703 L, M : R; 19704end record; 19705 19706for Q use record 19707 G at 0 range 0 .. 0; 19708 H at 0 range 1 .. 1; 19709 L at 0 range 2 .. 81; 19710 R at 0 range 82 .. 161; 19711end record; 19712@end example 19713 19714@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19715@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{28a}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{28b} 19716@section Handling of Records with Holes 19717 19718 19719@geindex Handling of Records with Holes 19720 19721As a result of alignment considerations, records may contain "holes" 19722or gaps 19723which do not correspond to the data bits of any of the components. 19724Record representation clauses can also result in holes in records. 19725 19726GNAT does not attempt to clear these holes, so in record objects, 19727they should be considered to hold undefined rubbish. The generated 19728equality routine just tests components so does not access these 19729undefined bits, and assignment and copy operations may or may not 19730preserve the contents of these holes (for assignments, the holes 19731in the target will in practice contain either the bits that are 19732present in the holes in the source, or the bits that were present 19733in the target before the assignment). 19734 19735If it is necessary to ensure that holes in records have all zero 19736bits, then record objects for which this initialization is desired 19737should be explicitly set to all zero values using Unchecked_Conversion 19738or address overlays. For example 19739 19740@example 19741type HRec is record 19742 C : Character; 19743 I : Integer; 19744end record; 19745@end example 19746 19747On typical machines, integers need to be aligned on a four-byte 19748boundary, resulting in three bytes of undefined rubbish following 19749the 8-bit field for C. To ensure that the hole in a variable of 19750type HRec is set to all zero bits, 19751you could for example do: 19752 19753@example 19754type Base is record 19755 Dummy1, Dummy2 : Integer := 0; 19756end record; 19757 19758BaseVar : Base; 19759RealVar : Hrec; 19760for RealVar'Address use BaseVar'Address; 19761@end example 19762 19763Now the 8-bytes of the value of RealVar start out containing all zero 19764bits. A safer approach is to just define dummy fields, avoiding the 19765holes, as in: 19766 19767@example 19768type HRec is record 19769 C : Character; 19770 Dummy1 : Short_Short_Integer := 0; 19771 Dummy2 : Short_Short_Integer := 0; 19772 Dummy3 : Short_Short_Integer := 0; 19773 I : Integer; 19774end record; 19775@end example 19776 19777And to make absolutely sure that the intent of this is followed, you 19778can use representation clauses: 19779 19780@example 19781for Hrec use record 19782 C at 0 range 0 .. 7; 19783 Dummy1 at 1 range 0 .. 7; 19784 Dummy2 at 2 range 0 .. 7; 19785 Dummy3 at 3 range 0 .. 7; 19786 I at 4 range 0 .. 31; 19787end record; 19788for Hrec'Size use 64; 19789@end example 19790 19791@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 19792@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{28c}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{28d} 19793@section Enumeration Clauses 19794 19795 19796The only restriction on enumeration clauses is that the range of values 19797must be representable. For the signed case, if one or more of the 19798representation values are negative, all values must be in the range: 19799 19800@example 19801System.Min_Int .. System.Max_Int 19802@end example 19803 19804For the unsigned case, where all values are nonnegative, the values must 19805be in the range: 19806 19807@example 198080 .. System.Max_Binary_Modulus; 19809@end example 19810 19811A @emph{confirming} representation clause is one in which the values range 19812from 0 in sequence, i.e., a clause that confirms the default representation 19813for an enumeration type. 19814Such a confirming representation 19815is permitted by these rules, and is specially recognized by the compiler so 19816that no extra overhead results from the use of such a clause. 19817 19818If an array has an index type which is an enumeration type to which an 19819enumeration clause has been applied, then the array is stored in a compact 19820manner. Consider the declarations: 19821 19822@example 19823type r is (A, B, C); 19824for r use (A => 1, B => 5, C => 10); 19825type t is array (r) of Character; 19826@end example 19827 19828The array type t corresponds to a vector with exactly three elements and 19829has a default size equal to @code{3*Character'Size}. This ensures efficient 19830use of space, but means that accesses to elements of the array will incur 19831the overhead of converting representation values to the corresponding 19832positional values, (i.e., the value delivered by the @code{Pos} attribute). 19833 19834@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 19835@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{28e}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{28f} 19836@section Address Clauses 19837 19838 19839@geindex Address Clause 19840 19841The reference manual allows a general restriction on representation clauses, 19842as found in RM 13.1(22): 19843 19844@quotation 19845 19846"An implementation need not support representation 19847items containing nonstatic expressions, except that 19848an implementation should support a representation item 19849for a given entity if each nonstatic expression in the 19850representation item is a name that statically denotes 19851a constant declared before the entity." 19852@end quotation 19853 19854In practice this is applicable only to address clauses, since this is the 19855only case in which a nonstatic expression is permitted by the syntax. As 19856the AARM notes in sections 13.1 (22.a-22.h): 19857 19858@quotation 19859 1986022.a Reason: This is to avoid the following sort of thing: 19861 1986222.b X : Integer := F(...); 19863Y : Address := G(...); 19864for X'Address use Y; 19865 1986622.c In the above, we have to evaluate the 19867initialization expression for X before we 19868know where to put the result. This seems 19869like an unreasonable implementation burden. 19870 1987122.d The above code should instead be written 19872like this: 19873 1987422.e Y : constant Address := G(...); 19875X : Integer := F(...); 19876for X'Address use Y; 19877 1987822.f This allows the expression 'Y' to be safely 19879evaluated before X is created. 19880 1988122.g The constant could be a formal parameter of mode in. 19882 1988322.h An implementation can support other nonstatic 19884expressions if it wants to. Expressions of type 19885Address are hardly ever static, but their value 19886might be known at compile time anyway in many 19887cases. 19888@end quotation 19889 19890GNAT does indeed permit many additional cases of nonstatic expressions. In 19891particular, if the type involved is elementary there are no restrictions 19892(since in this case, holding a temporary copy of the initialization value, 19893if one is present, is inexpensive). In addition, if there is no implicit or 19894explicit initialization, then there are no restrictions. GNAT will reject 19895only the case where all three of these conditions hold: 19896 19897 19898@itemize * 19899 19900@item 19901The type of the item is non-elementary (e.g., a record or array). 19902 19903@item 19904There is explicit or implicit initialization required for the object. 19905Note that access values are always implicitly initialized. 19906 19907@item 19908The address value is nonstatic. Here GNAT is more permissive than the 19909RM, and allows the address value to be the address of a previously declared 19910stand-alone variable, as long as it does not itself have an address clause. 19911 19912@example 19913Anchor : Some_Initialized_Type; 19914Overlay : Some_Initialized_Type; 19915for Overlay'Address use Anchor'Address; 19916@end example 19917 19918However, the prefix of the address clause cannot be an array component, or 19919a component of a discriminated record. 19920@end itemize 19921 19922As noted above in section 22.h, address values are typically nonstatic. In 19923particular the To_Address function, even if applied to a literal value, is 19924a nonstatic function call. To avoid this minor annoyance, GNAT provides 19925the implementation defined attribute 'To_Address. The following two 19926expressions have identical values: 19927 19928@geindex Attribute 19929 19930@geindex To_Address 19931 19932@example 19933To_Address (16#1234_0000#) 19934System'To_Address (16#1234_0000#); 19935@end example 19936 19937except that the second form is considered to be a static expression, and 19938thus when used as an address clause value is always permitted. 19939 19940Additionally, GNAT treats as static an address clause that is an 19941unchecked_conversion of a static integer value. This simplifies the porting 19942of legacy code, and provides a portable equivalent to the GNAT attribute 19943@code{To_Address}. 19944 19945Another issue with address clauses is the interaction with alignment 19946requirements. When an address clause is given for an object, the address 19947value must be consistent with the alignment of the object (which is usually 19948the same as the alignment of the type of the object). If an address clause 19949is given that specifies an inappropriately aligned address value, then the 19950program execution is erroneous. 19951 19952Since this source of erroneous behavior can have unfortunate effects on 19953machines with strict alignment requirements, GNAT 19954checks (at compile time if possible, generating a warning, or at execution 19955time with a run-time check) that the alignment is appropriate. If the 19956run-time check fails, then @code{Program_Error} is raised. This run-time 19957check is suppressed if range checks are suppressed, or if the special GNAT 19958check Alignment_Check is suppressed, or if 19959@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 19960suppressed by default on non-strict alignment machines (such as the x86). 19961 19962Finally, GNAT does not permit overlaying of objects of class-wide types. In 19963most cases, the compiler can detect an attempt at such overlays and will 19964generate a warning at compile time and a Program_Error exception at run time. 19965 19966@geindex Export 19967 19968An address clause cannot be given for an exported object. More 19969understandably the real restriction is that objects with an address 19970clause cannot be exported. This is because such variables are not 19971defined by the Ada program, so there is no external object to export. 19972 19973@geindex Import 19974 19975It is permissible to give an address clause and a pragma Import for the 19976same object. In this case, the variable is not really defined by the 19977Ada program, so there is no external symbol to be linked. The link name 19978and the external name are ignored in this case. The reason that we allow this 19979combination is that it provides a useful idiom to avoid unwanted 19980initializations on objects with address clauses. 19981 19982When an address clause is given for an object that has implicit or 19983explicit initialization, then by default initialization takes place. This 19984means that the effect of the object declaration is to overwrite the 19985memory at the specified address. This is almost always not what the 19986programmer wants, so GNAT will output a warning: 19987 19988@example 19989with System; 19990package G is 19991 type R is record 19992 M : Integer := 0; 19993 end record; 19994 19995 Ext : R; 19996 for Ext'Address use System'To_Address (16#1234_1234#); 19997 | 19998>>> warning: implicit initialization of "Ext" may 19999 modify overlaid storage 20000>>> warning: use pragma Import for "Ext" to suppress 20001 initialization (RM B(24)) 20002 20003end G; 20004@end example 20005 20006As indicated by the warning message, the solution is to use a (dummy) pragma 20007Import to suppress this initialization. The pragma tell the compiler that the 20008object is declared and initialized elsewhere. The following package compiles 20009without warnings (and the initialization is suppressed): 20010 20011@example 20012with System; 20013package G is 20014 type R is record 20015 M : Integer := 0; 20016 end record; 20017 20018 Ext : R; 20019 for Ext'Address use System'To_Address (16#1234_1234#); 20020 pragma Import (Ada, Ext); 20021end G; 20022@end example 20023 20024A final issue with address clauses involves their use for overlaying 20025variables, as in the following example: 20026 20027@geindex Overlaying of objects 20028 20029@example 20030A : Integer; 20031B : Integer; 20032for B'Address use A'Address; 20033@end example 20034 20035or alternatively, using the form recommended by the RM: 20036 20037@example 20038A : Integer; 20039Addr : constant Address := A'Address; 20040B : Integer; 20041for B'Address use Addr; 20042@end example 20043 20044In both of these cases, @code{A} and @code{B} become aliased to one another 20045via the address clause. This use of address clauses to overlay 20046variables, achieving an effect similar to unchecked conversion 20047was erroneous in Ada 83, but in Ada 95 and Ada 2005 20048the effect is implementation defined. Furthermore, the 20049Ada RM specifically recommends that in a situation 20050like this, @code{B} should be subject to the following 20051implementation advice (RM 13.3(19)): 20052 20053@quotation 20054 20055"19 If the Address of an object is specified, or it is imported 20056or exported, then the implementation should not perform 20057optimizations based on assumptions of no aliases." 20058@end quotation 20059 20060GNAT follows this recommendation, and goes further by also applying 20061this recommendation to the overlaid variable (@code{A} in the above example) 20062in this case. This means that the overlay works "as expected", in that 20063a modification to one of the variables will affect the value of the other. 20064 20065More generally, GNAT interprets this recommendation conservatively for 20066address clauses: in the cases other than overlays, it considers that the 20067object is effectively subject to pragma @code{Volatile} and implements the 20068associated semantics. 20069 20070Note that when address clause overlays are used in this way, there is an 20071issue of unintentional initialization, as shown by this example: 20072 20073@example 20074package Overwrite_Record is 20075 type R is record 20076 A : Character := 'C'; 20077 B : Character := 'A'; 20078 end record; 20079 X : Short_Integer := 3; 20080 Y : R; 20081 for Y'Address use X'Address; 20082 | 20083>>> warning: default initialization of "Y" may 20084 modify "X", use pragma Import for "Y" to 20085 suppress initialization (RM B.1(24)) 20086 20087end Overwrite_Record; 20088@end example 20089 20090Here the default initialization of @code{Y} will clobber the value 20091of @code{X}, which justifies the warning. The warning notes that 20092this effect can be eliminated by adding a @code{pragma Import} 20093which suppresses the initialization: 20094 20095@example 20096package Overwrite_Record is 20097 type R is record 20098 A : Character := 'C'; 20099 B : Character := 'A'; 20100 end record; 20101 X : Short_Integer := 3; 20102 Y : R; 20103 for Y'Address use X'Address; 20104 pragma Import (Ada, Y); 20105end Overwrite_Record; 20106@end example 20107 20108Note that the use of @code{pragma Initialize_Scalars} may cause variables to 20109be initialized when they would not otherwise have been in the absence 20110of the use of this pragma. This may cause an overlay to have this 20111unintended clobbering effect. The compiler avoids this for scalar 20112types, but not for composite objects (where in general the effect 20113of @code{Initialize_Scalars} is part of the initialization routine 20114for the composite object: 20115 20116@example 20117pragma Initialize_Scalars; 20118with Ada.Text_IO; use Ada.Text_IO; 20119procedure Overwrite_Array is 20120 type Arr is array (1 .. 5) of Integer; 20121 X : Arr := (others => 1); 20122 A : Arr; 20123 for A'Address use X'Address; 20124 | 20125>>> warning: default initialization of "A" may 20126 modify "X", use pragma Import for "A" to 20127 suppress initialization (RM B.1(24)) 20128 20129begin 20130 if X /= Arr'(others => 1) then 20131 Put_Line ("X was clobbered"); 20132 else 20133 Put_Line ("X was not clobbered"); 20134 end if; 20135end Overwrite_Array; 20136@end example 20137 20138The above program generates the warning as shown, and at execution 20139time, prints @code{X was clobbered}. If the @code{pragma Import} is 20140added as suggested: 20141 20142@example 20143pragma Initialize_Scalars; 20144with Ada.Text_IO; use Ada.Text_IO; 20145procedure Overwrite_Array is 20146 type Arr is array (1 .. 5) of Integer; 20147 X : Arr := (others => 1); 20148 A : Arr; 20149 for A'Address use X'Address; 20150 pragma Import (Ada, A); 20151begin 20152 if X /= Arr'(others => 1) then 20153 Put_Line ("X was clobbered"); 20154 else 20155 Put_Line ("X was not clobbered"); 20156 end if; 20157end Overwrite_Array; 20158@end example 20159 20160then the program compiles without the warning and when run will generate 20161the output @code{X was not clobbered}. 20162 20163@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 20164@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{290}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{291} 20165@section Use of Address Clauses for Memory-Mapped I/O 20166 20167 20168@geindex Memory-mapped I/O 20169 20170A common pattern is to use an address clause to map an atomic variable to 20171a location in memory that corresponds to a memory-mapped I/O operation or 20172operations, for example: 20173 20174@example 20175type Mem_Word is record 20176 A,B,C,D : Byte; 20177end record; 20178pragma Atomic (Mem_Word); 20179for Mem_Word_Size use 32; 20180 20181Mem : Mem_Word; 20182for Mem'Address use some-address; 20183... 20184Temp := Mem; 20185Temp.A := 32; 20186Mem := Temp; 20187@end example 20188 20189For a full access (reference or modification) of the variable (Mem) in this 20190case, as in the above examples, GNAT guarantees that the entire atomic word 20191will be accessed, in accordance with the RM C.6(15) clause. 20192 20193A problem arises with a component access such as: 20194 20195@example 20196Mem.A := 32; 20197@end example 20198 20199Note that the component A is not declared as atomic. This means that it is 20200not clear what this assignment means. It could correspond to full word read 20201and write as given in the first example, or on architectures that supported 20202such an operation it might be a single byte store instruction. The RM does 20203not have anything to say in this situation, and GNAT does not make any 20204guarantee. The code generated may vary from target to target. GNAT will issue 20205a warning in such a case: 20206 20207@example 20208Mem.A := 32; 20209| 20210>>> warning: access to non-atomic component of atomic array, 20211 may cause unexpected accesses to atomic object 20212@end example 20213 20214It is best to be explicit in this situation, by either declaring the 20215components to be atomic if you want the byte store, or explicitly writing 20216the full word access sequence if that is what the hardware requires. 20217Alternatively, if the full word access sequence is required, GNAT also 20218provides the pragma @code{Volatile_Full_Access} which can be used in lieu of 20219pragma @code{Atomic} and will give the additional guarantee. 20220 20221@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 20222@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{292}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{293} 20223@section Effect of Convention on Representation 20224 20225 20226@geindex Convention 20227@geindex effect on representation 20228 20229Normally the specification of a foreign language convention for a type or 20230an object has no effect on the chosen representation. In particular, the 20231representation chosen for data in GNAT generally meets the standard system 20232conventions, and for example records are laid out in a manner that is 20233consistent with C. This means that specifying convention C (for example) 20234has no effect. 20235 20236There are four exceptions to this general rule: 20237 20238 20239@itemize * 20240 20241@item 20242@emph{Convention Fortran and array subtypes}. 20243 20244If pragma Convention Fortran is specified for an array subtype, then in 20245accordance with the implementation advice in section 3.6.2(11) of the 20246Ada Reference Manual, the array will be stored in a Fortran-compatible 20247column-major manner, instead of the normal default row-major order. 20248 20249@item 20250@emph{Convention C and enumeration types} 20251 20252GNAT normally stores enumeration types in 8, 16, or 32 bits as required 20253to accommodate all values of the type. For example, for the enumeration 20254type declared by: 20255 20256@example 20257type Color is (Red, Green, Blue); 20258@end example 20259 202608 bits is sufficient to store all values of the type, so by default, objects 20261of type @code{Color} will be represented using 8 bits. However, normal C 20262convention is to use 32 bits for all enum values in C, since enum values 20263are essentially of type int. If pragma @code{Convention C} is specified for an 20264Ada enumeration type, then the size is modified as necessary (usually to 2026532 bits) to be consistent with the C convention for enum values. 20266 20267Note that this treatment applies only to types. If Convention C is given for 20268an enumeration object, where the enumeration type is not Convention C, then 20269Object_Size bits are allocated. For example, for a normal enumeration type, 20270with less than 256 elements, only 8 bits will be allocated for the object. 20271Since this may be a surprise in terms of what C expects, GNAT will issue a 20272warning in this situation. The warning can be suppressed by giving an explicit 20273size clause specifying the desired size. 20274 20275@item 20276@emph{Convention C/Fortran and Boolean types} 20277 20278In C, the usual convention for boolean values, that is values used for 20279conditions, is that zero represents false, and nonzero values represent 20280true. In Ada, the normal convention is that two specific values, typically 202810/1, are used to represent false/true respectively. 20282 20283Fortran has a similar convention for @code{LOGICAL} values (any nonzero 20284value represents true). 20285 20286To accommodate the Fortran and C conventions, if a pragma Convention specifies 20287C or Fortran convention for a derived Boolean, as in the following example: 20288 20289@example 20290type C_Switch is new Boolean; 20291pragma Convention (C, C_Switch); 20292@end example 20293 20294then the GNAT generated code will treat any nonzero value as true. For truth 20295values generated by GNAT, the conventional value 1 will be used for True, but 20296when one of these values is read, any nonzero value is treated as True. 20297@end itemize 20298 20299@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 20300@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{294}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{295} 20301@section Conventions and Anonymous Access Types 20302 20303 20304@geindex Anonymous access types 20305 20306@geindex Convention for anonymous access types 20307 20308The RM is not entirely clear on convention handling in a number of cases, 20309and in particular, it is not clear on the convention to be given to 20310anonymous access types in general, and in particular what is to be 20311done for the case of anonymous access-to-subprogram. 20312 20313In GNAT, we decide that if an explicit Convention is applied 20314to an object or component, and its type is such an anonymous type, 20315then the convention will apply to this anonymous type as well. This 20316seems to make sense since it is anomolous in any case to have a 20317different convention for an object and its type, and there is clearly 20318no way to explicitly specify a convention for an anonymous type, since 20319it doesn't have a name to specify! 20320 20321Furthermore, we decide that if a convention is applied to a record type, 20322then this convention is inherited by any of its components that are of an 20323anonymous access type which do not have an explicitly specified convention. 20324 20325The following program shows these conventions in action: 20326 20327@example 20328package ConvComp is 20329 type Foo is range 1 .. 10; 20330 type T1 is record 20331 A : access function (X : Foo) return Integer; 20332 B : Integer; 20333 end record; 20334 pragma Convention (C, T1); 20335 20336 type T2 is record 20337 A : access function (X : Foo) return Integer; 20338 pragma Convention (C, A); 20339 B : Integer; 20340 end record; 20341 pragma Convention (COBOL, T2); 20342 20343 type T3 is record 20344 A : access function (X : Foo) return Integer; 20345 pragma Convention (COBOL, A); 20346 B : Integer; 20347 end record; 20348 pragma Convention (C, T3); 20349 20350 type T4 is record 20351 A : access function (X : Foo) return Integer; 20352 B : Integer; 20353 end record; 20354 pragma Convention (COBOL, T4); 20355 20356 function F (X : Foo) return Integer; 20357 pragma Convention (C, F); 20358 20359 function F (X : Foo) return Integer is (13); 20360 20361 TV1 : T1 := (F'Access, 12); -- OK 20362 TV2 : T2 := (F'Access, 13); -- OK 20363 20364 TV3 : T3 := (F'Access, 13); -- ERROR 20365 | 20366>>> subprogram "F" has wrong convention 20367>>> does not match access to subprogram declared at line 17 20368 38. TV4 : T4 := (F'Access, 13); -- ERROR 20369 | 20370>>> subprogram "F" has wrong convention 20371>>> does not match access to subprogram declared at line 24 20372 39. end ConvComp; 20373@end example 20374 20375@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 20376@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{296}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{297} 20377@section Determining the Representations chosen by GNAT 20378 20379 20380@geindex Representation 20381@geindex determination of 20382 20383@geindex -gnatR (gcc) 20384 20385Although the descriptions in this section are intended to be complete, it is 20386often easier to simply experiment to see what GNAT accepts and what the 20387effect is on the layout of types and objects. 20388 20389As required by the Ada RM, if a representation clause is not accepted, then 20390it must be rejected as illegal by the compiler. However, when a 20391representation clause or pragma is accepted, there can still be questions 20392of what the compiler actually does. For example, if a partial record 20393representation clause specifies the location of some components and not 20394others, then where are the non-specified components placed? Or if pragma 20395@code{Pack} is used on a record, then exactly where are the resulting 20396fields placed? The section on pragma @code{Pack} in this chapter can be 20397used to answer the second question, but it is often easier to just see 20398what the compiler does. 20399 20400For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 20401with this option, then the compiler will output information on the actual 20402representations chosen, in a format similar to source representation 20403clauses. For example, if we compile the package: 20404 20405@example 20406package q is 20407 type r (x : boolean) is tagged record 20408 case x is 20409 when True => S : String (1 .. 100); 20410 when False => null; 20411 end case; 20412 end record; 20413 20414 type r2 is new r (false) with record 20415 y2 : integer; 20416 end record; 20417 20418 for r2 use record 20419 y2 at 16 range 0 .. 31; 20420 end record; 20421 20422 type x is record 20423 y : character; 20424 end record; 20425 20426 type x1 is array (1 .. 10) of x; 20427 for x1'component_size use 11; 20428 20429 type ia is access integer; 20430 20431 type Rb1 is array (1 .. 13) of Boolean; 20432 pragma Pack (rb1); 20433 20434 type Rb2 is array (1 .. 65) of Boolean; 20435 pragma Pack (rb2); 20436 20437 type x2 is record 20438 l1 : Boolean; 20439 l2 : Duration; 20440 l3 : Float; 20441 l4 : Boolean; 20442 l5 : Rb1; 20443 l6 : Rb2; 20444 end record; 20445 pragma Pack (x2); 20446end q; 20447@end example 20448 20449using the switch @emph{-gnatR} we obtain the following output: 20450 20451@example 20452Representation information for unit q 20453------------------------------------- 20454 20455for r'Size use ??; 20456for r'Alignment use 4; 20457for r use record 20458 x at 4 range 0 .. 7; 20459 _tag at 0 range 0 .. 31; 20460 s at 5 range 0 .. 799; 20461end record; 20462 20463for r2'Size use 160; 20464for r2'Alignment use 4; 20465for r2 use record 20466 x at 4 range 0 .. 7; 20467 _tag at 0 range 0 .. 31; 20468 _parent at 0 range 0 .. 63; 20469 y2 at 16 range 0 .. 31; 20470end record; 20471 20472for x'Size use 8; 20473for x'Alignment use 1; 20474for x use record 20475 y at 0 range 0 .. 7; 20476end record; 20477 20478for x1'Size use 112; 20479for x1'Alignment use 1; 20480for x1'Component_Size use 11; 20481 20482for rb1'Size use 13; 20483for rb1'Alignment use 2; 20484for rb1'Component_Size use 1; 20485 20486for rb2'Size use 72; 20487for rb2'Alignment use 1; 20488for rb2'Component_Size use 1; 20489 20490for x2'Size use 224; 20491for x2'Alignment use 4; 20492for x2 use record 20493 l1 at 0 range 0 .. 0; 20494 l2 at 0 range 1 .. 64; 20495 l3 at 12 range 0 .. 31; 20496 l4 at 16 range 0 .. 0; 20497 l5 at 16 range 1 .. 13; 20498 l6 at 18 range 0 .. 71; 20499end record; 20500@end example 20501 20502The Size values are actually the Object_Size, i.e., the default size that 20503will be allocated for objects of the type. 20504The @code{??} size for type r indicates that we have a variant record, and the 20505actual size of objects will depend on the discriminant value. 20506 20507The Alignment values show the actual alignment chosen by the compiler 20508for each record or array type. 20509 20510The record representation clause for type r shows where all fields 20511are placed, including the compiler generated tag field (whose location 20512cannot be controlled by the programmer). 20513 20514The record representation clause for the type extension r2 shows all the 20515fields present, including the parent field, which is a copy of the fields 20516of the parent type of r2, i.e., r1. 20517 20518The component size and size clauses for types rb1 and rb2 show 20519the exact effect of pragma @code{Pack} on these arrays, and the record 20520representation clause for type x2 shows how pragma @cite{Pack} affects 20521this record type. 20522 20523In some cases, it may be useful to cut and paste the representation clauses 20524generated by the compiler into the original source to fix and guarantee 20525the actual representation to be used. 20526 20527@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 20528@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{298}@anchor{gnat_rm/standard_library_routines id1}@anchor{299} 20529@chapter Standard Library Routines 20530 20531 20532The Ada Reference Manual contains in Annex A a full description of an 20533extensive set of standard library routines that can be used in any Ada 20534program, and which must be provided by all Ada compilers. They are 20535analogous to the standard C library used by C programs. 20536 20537GNAT implements all of the facilities described in annex A, and for most 20538purposes the description in the Ada Reference Manual, or appropriate Ada 20539text book, will be sufficient for making use of these facilities. 20540 20541In the case of the input-output facilities, 20542@ref{f,,The Implementation of Standard I/O}, 20543gives details on exactly how GNAT interfaces to the 20544file system. For the remaining packages, the Ada Reference Manual 20545should be sufficient. The following is a list of the packages included, 20546together with a brief description of the functionality that is provided. 20547 20548For completeness, references are included to other predefined library 20549routines defined in other sections of the Ada Reference Manual (these are 20550cross-indexed from Annex A). For further details see the relevant 20551package declarations in the run-time library. In particular, a few units 20552are not implemented, as marked by the presence of pragma Unimplemented_Unit, 20553and in this case the package declaration contains comments explaining why 20554the unit is not implemented. 20555 20556 20557@table @asis 20558 20559@item @code{Ada} @emph{(A.2)} 20560 20561This is a parent package for all the standard library packages. It is 20562usually included implicitly in your program, and itself contains no 20563useful data or routines. 20564 20565@item @code{Ada.Assertions} @emph{(11.4.2)} 20566 20567@code{Assertions} provides the @code{Assert} subprograms, and also 20568the declaration of the @code{Assertion_Error} exception. 20569 20570@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 20571 20572@code{Asynchronous_Task_Control} provides low level facilities for task 20573synchronization. It is typically not implemented. See package spec for details. 20574 20575@item @code{Ada.Calendar} @emph{(9.6)} 20576 20577@code{Calendar} provides time of day access, and routines for 20578manipulating times and durations. 20579 20580@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 20581 20582This package provides additional arithmetic 20583operations for @code{Calendar}. 20584 20585@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 20586 20587This package provides formatting operations for @code{Calendar}. 20588 20589@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 20590 20591This package provides additional @code{Calendar} facilities 20592for handling time zones. 20593 20594@item @code{Ada.Characters} @emph{(A.3.1)} 20595 20596This is a dummy parent package that contains no useful entities 20597 20598@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 20599 20600This package provides character conversion functions. 20601 20602@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 20603 20604This package provides some basic character handling capabilities, 20605including classification functions for classes of characters (e.g., test 20606for letters, or digits). 20607 20608@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 20609 20610This package includes a complete set of definitions of the characters 20611that appear in type CHARACTER. It is useful for writing programs that 20612will run in international environments. For example, if you want an 20613upper case E with an acute accent in a string, it is often better to use 20614the definition of @code{UC_E_Acute} in this package. Then your program 20615will print in an understandable manner even if your environment does not 20616support these extended characters. 20617 20618@item @code{Ada.Command_Line} @emph{(A.15)} 20619 20620This package provides access to the command line parameters and the name 20621of the current program (analogous to the use of @code{argc} and @code{argv} 20622in C), and also allows the exit status for the program to be set in a 20623system-independent manner. 20624 20625@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20626 20627This package provides text input and output of complex numbers. 20628 20629@item @code{Ada.Containers} @emph{(A.18.1)} 20630 20631A top level package providing a few basic definitions used by all the 20632following specific child packages that provide specific kinds of 20633containers. 20634@end table 20635 20636@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20637 20638@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20639 20640@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20641 20642@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20643 20644@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20645 20646@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20647 20648@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20649 20650@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20651 20652@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20653 20654@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20655 20656@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20657 20658@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20659 20660@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20661 20662@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20663 20664@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20665 20666@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20667 20668@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20669 20670@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20671 20672@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20673 20674@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20675 20676@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20677 20678@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20679 20680@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20681 20682 20683@table @asis 20684 20685@item @code{Ada.Directories} @emph{(A.16)} 20686 20687This package provides operations on directories. 20688 20689@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20690 20691This package provides additional directory operations handling 20692hiearchical file names. 20693 20694@item @code{Ada.Directories.Information} @emph{(A.16)} 20695 20696This is an implementation defined package for additional directory 20697operations, which is not implemented in GNAT. 20698 20699@item @code{Ada.Decimal} @emph{(F.2)} 20700 20701This package provides constants describing the range of decimal numbers 20702implemented, and also a decimal divide routine (analogous to the COBOL 20703verb DIVIDE ... GIVING ... REMAINDER ...) 20704 20705@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20706 20707This package provides input-output using a model of a set of records of 20708fixed-length, containing an arbitrary definite Ada type, indexed by an 20709integer record number. 20710 20711@item @code{Ada.Dispatching} @emph{(D.2.1)} 20712 20713A parent package containing definitions for task dispatching operations. 20714 20715@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20716 20717Not implemented in GNAT. 20718 20719@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20720 20721Not implemented in GNAT. 20722 20723@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20724 20725Not implemented in GNAT. 20726 20727@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20728 20729This package allows the priorities of a task to be adjusted dynamically 20730as the task is running. 20731 20732@item @code{Ada.Environment_Variables} @emph{(A.17)} 20733 20734This package provides facilities for accessing environment variables. 20735 20736@item @code{Ada.Exceptions} @emph{(11.4.1)} 20737 20738This package provides additional information on exceptions, and also 20739contains facilities for treating exceptions as data objects, and raising 20740exceptions with associated messages. 20741 20742@item @code{Ada.Execution_Time} @emph{(D.14)} 20743 20744This package provides CPU clock functionalities. It is not implemented on 20745all targets (see package spec for details). 20746 20747@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20748 20749Not implemented in GNAT. 20750 20751@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'} 20752 20753Not implemented in GNAT. 20754 20755@item @code{Ada.Finalization} @emph{(7.6)} 20756 20757This package contains the declarations and subprograms to support the 20758use of controlled types, providing for automatic initialization and 20759finalization (analogous to the constructors and destructors of C++). 20760 20761@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20762 20763A library level instantiation of Text_IO.Float_IO for type Float. 20764 20765@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 20766 20767A library level instantiation of Wide_Text_IO.Float_IO for type Float. 20768 20769@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 20770 20771A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 20772 20773@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 20774 20775A library level instantiation of Text_IO.Integer_IO for type Integer. 20776 20777@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 20778 20779A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 20780 20781@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 20782 20783A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 20784 20785@item @code{Ada.Interrupts} @emph{(C.3.2)} 20786 20787This package provides facilities for interfacing to interrupts, which 20788includes the set of signals or conditions that can be raised and 20789recognized as interrupts. 20790 20791@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 20792 20793This package provides the set of interrupt names (actually signal 20794or condition names) that can be handled by GNAT. 20795 20796@item @code{Ada.IO_Exceptions} @emph{(A.13)} 20797 20798This package defines the set of exceptions that can be raised by use of 20799the standard IO packages. 20800 20801@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 20802 20803This package provides a generic interface to generalized iterators. 20804 20805@item @code{Ada.Locales} @emph{(A.19)} 20806 20807This package provides declarations providing information (Language 20808and Country) about the current locale. 20809 20810@item @code{Ada.Numerics} 20811 20812This package contains some standard constants and exceptions used 20813throughout the numerics packages. Note that the constants pi and e are 20814defined here, and it is better to use these definitions than rolling 20815your own. 20816 20817@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 20818 20819Provides operations on arrays of complex numbers. 20820 20821@item @code{Ada.Numerics.Complex_Elementary_Functions} 20822 20823Provides the implementation of standard elementary functions (such as 20824log and trigonometric functions) operating on complex numbers using the 20825standard @code{Float} and the @code{Complex} and @code{Imaginary} types 20826created by the package @code{Numerics.Complex_Types}. 20827 20828@item @code{Ada.Numerics.Complex_Types} 20829 20830This is a predefined instantiation of 20831@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 20832build the type @code{Complex} and @code{Imaginary}. 20833 20834@item @code{Ada.Numerics.Discrete_Random} 20835 20836This generic package provides a random number generator suitable for generating 20837uniformly distributed values of a specified discrete subtype. 20838 20839@item @code{Ada.Numerics.Float_Random} 20840 20841This package provides a random number generator suitable for generating 20842uniformly distributed floating point values in the unit interval. 20843 20844@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 20845 20846This is a generic version of the package that provides the 20847implementation of standard elementary functions (such as log and 20848trigonometric functions) for an arbitrary complex type. 20849 20850The following predefined instantiations of this package are provided: 20851 20852 20853@itemize * 20854 20855@item 20856@code{Short_Float} 20857 20858@code{Ada.Numerics.Short_Complex_Elementary_Functions} 20859 20860@item 20861@code{Float} 20862 20863@code{Ada.Numerics.Complex_Elementary_Functions} 20864 20865@item 20866@code{Long_Float} 20867 20868@code{Ada.Numerics.Long_Complex_Elementary_Functions} 20869@end itemize 20870 20871@item @code{Ada.Numerics.Generic_Complex_Types} 20872 20873This is a generic package that allows the creation of complex types, 20874with associated complex arithmetic operations. 20875 20876The following predefined instantiations of this package exist 20877 20878 20879@itemize * 20880 20881@item 20882@code{Short_Float} 20883 20884@code{Ada.Numerics.Short_Complex_Complex_Types} 20885 20886@item 20887@code{Float} 20888 20889@code{Ada.Numerics.Complex_Complex_Types} 20890 20891@item 20892@code{Long_Float} 20893 20894@code{Ada.Numerics.Long_Complex_Complex_Types} 20895@end itemize 20896 20897@item @code{Ada.Numerics.Generic_Elementary_Functions} 20898 20899This is a generic package that provides the implementation of standard 20900elementary functions (such as log an trigonometric functions) for an 20901arbitrary float type. 20902 20903The following predefined instantiations of this package exist 20904 20905 20906@itemize * 20907 20908@item 20909@code{Short_Float} 20910 20911@code{Ada.Numerics.Short_Elementary_Functions} 20912 20913@item 20914@code{Float} 20915 20916@code{Ada.Numerics.Elementary_Functions} 20917 20918@item 20919@code{Long_Float} 20920 20921@code{Ada.Numerics.Long_Elementary_Functions} 20922@end itemize 20923 20924@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 20925 20926Generic operations on arrays of reals 20927 20928@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 20929 20930Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 20931 20932@item @code{Ada.Real_Time} @emph{(D.8)} 20933 20934This package provides facilities similar to those of @code{Calendar}, but 20935operating with a finer clock suitable for real time control. Note that 20936annex D requires that there be no backward clock jumps, and GNAT generally 20937guarantees this behavior, but of course if the external clock on which 20938the GNAT runtime depends is deliberately reset by some external event, 20939then such a backward jump may occur. 20940 20941@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 20942 20943Not implemented in GNAT. 20944 20945@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 20946 20947This package provides input-output facilities for sequential files, 20948which can contain a sequence of values of a single type, which can be 20949any Ada type, including indefinite (unconstrained) types. 20950 20951@item @code{Ada.Storage_IO} @emph{(A.9)} 20952 20953This package provides a facility for mapping arbitrary Ada types to and 20954from a storage buffer. It is primarily intended for the creation of new 20955IO packages. 20956 20957@item @code{Ada.Streams} @emph{(13.13.1)} 20958 20959This is a generic package that provides the basic support for the 20960concept of streams as used by the stream attributes (@code{Input}, 20961@code{Output}, @code{Read} and @code{Write}). 20962 20963@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 20964 20965This package is a specialization of the type @code{Streams} defined in 20966package @code{Streams} together with a set of operations providing 20967Stream_IO capability. The Stream_IO model permits both random and 20968sequential access to a file which can contain an arbitrary set of values 20969of one or more Ada types. 20970 20971@item @code{Ada.Strings} @emph{(A.4.1)} 20972 20973This package provides some basic constants used by the string handling 20974packages. 20975 20976@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 20977 20978This package provides facilities for handling variable length 20979strings. The bounded model requires a maximum length. It is thus 20980somewhat more limited than the unbounded model, but avoids the use of 20981dynamic allocation or finalization. 20982 20983@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20984 20985Provides case-insensitive comparisons of bounded strings 20986 20987@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 20988 20989This package provides a generic hash function for bounded strings 20990 20991@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20992 20993This package provides a generic hash function for bounded strings that 20994converts the string to be hashed to lower case. 20995 20996@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 20997 20998This package provides a comparison function for bounded strings that works 20999in a case insensitive manner by converting to lower case before the comparison. 21000 21001@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 21002 21003This package provides facilities for handling fixed length strings. 21004 21005@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 21006 21007This package provides an equality function for fixed strings that compares 21008the strings after converting both to lower case. 21009 21010@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 21011 21012This package provides a case insensitive hash function for fixed strings that 21013converts the string to lower case before computing the hash. 21014 21015@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 21016 21017This package provides a comparison function for fixed strings that works 21018in a case insensitive manner by converting to lower case before the comparison. 21019 21020@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 21021 21022This package provides a hash function for strings. 21023 21024@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 21025 21026This package provides a hash function for strings that is case insensitive. 21027The string is converted to lower case before computing the hash. 21028 21029@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 21030 21031This package provides a comparison function for\strings that works 21032in a case insensitive manner by converting to lower case before the comparison. 21033 21034@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 21035 21036This package provides facilities for handling character mappings and 21037arbitrarily defined subsets of characters. For instance it is useful in 21038defining specialized translation tables. 21039 21040@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 21041 21042This package provides a standard set of predefined mappings and 21043predefined character sets. For example, the standard upper to lower case 21044conversion table is found in this package. Note that upper to lower case 21045conversion is non-trivial if you want to take the entire set of 21046characters, including extended characters like E with an acute accent, 21047into account. You should use the mappings in this package (rather than 21048adding 32 yourself) to do case mappings. 21049 21050@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 21051 21052This package provides facilities for handling variable length 21053strings. The unbounded model allows arbitrary length strings, but 21054requires the use of dynamic allocation and finalization. 21055 21056@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 21057 21058Provides case-insensitive comparisons of unbounded strings 21059 21060@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 21061 21062This package provides a generic hash function for unbounded strings 21063 21064@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 21065 21066This package provides a generic hash function for unbounded strings that 21067converts the string to be hashed to lower case. 21068 21069@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 21070 21071This package provides a comparison function for unbounded strings that works 21072in a case insensitive manner by converting to lower case before the comparison. 21073 21074@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 21075 21076This package provides basic definitions for dealing with UTF-encoded strings. 21077 21078@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 21079 21080This package provides conversion functions for UTF-encoded strings. 21081@end table 21082 21083@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 21084 21085@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 21086 21087 21088@table @asis 21089 21090@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 21091 21092These packages provide facilities for handling UTF encodings for 21093Strings, Wide_Strings and Wide_Wide_Strings. 21094@end table 21095 21096@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 21097 21098@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 21099 21100@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 21101 21102 21103@table @asis 21104 21105@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 21106 21107These packages provide analogous capabilities to the corresponding 21108packages without @code{Wide_} in the name, but operate with the types 21109@code{Wide_String} and @code{Wide_Character} instead of @code{String} 21110and @code{Character}. Versions of all the child packages are available. 21111@end table 21112 21113@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 21114 21115@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 21116 21117@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 21118 21119 21120@table @asis 21121 21122@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 21123 21124These packages provide analogous capabilities to the corresponding 21125packages without @code{Wide_} in the name, but operate with the types 21126@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 21127of @code{String} and @code{Character}. 21128 21129@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 21130 21131This package provides facilities for synchronizing tasks at a low level 21132with barriers. 21133 21134@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 21135 21136This package provides some standard facilities for controlling task 21137communication in a synchronous manner. 21138 21139@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 21140 21141Not implemented in GNAT. 21142 21143@item @code{Ada.Tags} 21144 21145This package contains definitions for manipulation of the tags of tagged 21146values. 21147 21148@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 21149 21150This package provides a way of constructing tagged class-wide values given 21151only the tag value. 21152 21153@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 21154 21155This package provides the capability of associating arbitrary 21156task-specific data with separate tasks. 21157 21158@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 21159 21160This package provides capabilities for task identification. 21161 21162@item @code{Ada.Task_Termination} @emph{(C.7.3)} 21163 21164This package provides control over task termination. 21165 21166@item @code{Ada.Text_IO} 21167 21168This package provides basic text input-output capabilities for 21169character, string and numeric data. The subpackages of this 21170package are listed next. Note that although these are defined 21171as subpackages in the RM, they are actually transparently 21172implemented as child packages in GNAT, meaning that they 21173are only loaded if needed. 21174 21175@item @code{Ada.Text_IO.Decimal_IO} 21176 21177Provides input-output facilities for decimal fixed-point types 21178 21179@item @code{Ada.Text_IO.Enumeration_IO} 21180 21181Provides input-output facilities for enumeration types. 21182 21183@item @code{Ada.Text_IO.Fixed_IO} 21184 21185Provides input-output facilities for ordinary fixed-point types. 21186 21187@item @code{Ada.Text_IO.Float_IO} 21188 21189Provides input-output facilities for float types. The following 21190predefined instantiations of this generic package are available: 21191 21192 21193@itemize * 21194 21195@item 21196@code{Short_Float} 21197 21198@code{Short_Float_Text_IO} 21199 21200@item 21201@code{Float} 21202 21203@code{Float_Text_IO} 21204 21205@item 21206@code{Long_Float} 21207 21208@code{Long_Float_Text_IO} 21209@end itemize 21210 21211@item @code{Ada.Text_IO.Integer_IO} 21212 21213Provides input-output facilities for integer types. The following 21214predefined instantiations of this generic package are available: 21215 21216 21217@itemize * 21218 21219@item 21220@code{Short_Short_Integer} 21221 21222@code{Ada.Short_Short_Integer_Text_IO} 21223 21224@item 21225@code{Short_Integer} 21226 21227@code{Ada.Short_Integer_Text_IO} 21228 21229@item 21230@code{Integer} 21231 21232@code{Ada.Integer_Text_IO} 21233 21234@item 21235@code{Long_Integer} 21236 21237@code{Ada.Long_Integer_Text_IO} 21238 21239@item 21240@code{Long_Long_Integer} 21241 21242@code{Ada.Long_Long_Integer_Text_IO} 21243@end itemize 21244 21245@item @code{Ada.Text_IO.Modular_IO} 21246 21247Provides input-output facilities for modular (unsigned) types. 21248 21249@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 21250 21251Provides input-output facilities for bounded strings. 21252 21253@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 21254 21255This package provides basic text input-output capabilities for complex 21256data. 21257 21258@item @code{Ada.Text_IO.Editing (F.3.3)} 21259 21260This package contains routines for edited output, analogous to the use 21261of pictures in COBOL. The picture formats used by this package are a 21262close copy of the facility in COBOL. 21263 21264@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 21265 21266This package provides a facility that allows Text_IO files to be treated 21267as streams, so that the stream attributes can be used for writing 21268arbitrary data, including binary data, to Text_IO files. 21269 21270@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 21271 21272This package provides input-output facilities for unbounded strings. 21273 21274@item @code{Ada.Unchecked_Conversion (13.9)} 21275 21276This generic package allows arbitrary conversion from one type to 21277another of the same size, providing for breaking the type safety in 21278special circumstances. 21279 21280If the types have the same Size (more accurately the same Value_Size), 21281then the effect is simply to transfer the bits from the source to the 21282target type without any modification. This usage is well defined, and 21283for simple types whose representation is typically the same across 21284all implementations, gives a portable method of performing such 21285conversions. 21286 21287If the types do not have the same size, then the result is implementation 21288defined, and thus may be non-portable. The following describes how GNAT 21289handles such unchecked conversion cases. 21290 21291If the types are of different sizes, and are both discrete types, then 21292the effect is of a normal type conversion without any constraint checking. 21293In particular if the result type has a larger size, the result will be 21294zero or sign extended. If the result type has a smaller size, the result 21295will be truncated by ignoring high order bits. 21296 21297If the types are of different sizes, and are not both discrete types, 21298then the conversion works as though pointers were created to the source 21299and target, and the pointer value is converted. The effect is that bits 21300are copied from successive low order storage units and bits of the source 21301up to the length of the target type. 21302 21303A warning is issued if the lengths differ, since the effect in this 21304case is implementation dependent, and the above behavior may not match 21305that of some other compiler. 21306 21307A pointer to one type may be converted to a pointer to another type using 21308unchecked conversion. The only case in which the effect is undefined is 21309when one or both pointers are pointers to unconstrained array types. In 21310this case, the bounds information may get incorrectly transferred, and in 21311particular, GNAT uses double size pointers for such types, and it is 21312meaningless to convert between such pointer types. GNAT will issue a 21313warning if the alignment of the target designated type is more strict 21314than the alignment of the source designated type (since the result may 21315be unaligned in this case). 21316 21317A pointer other than a pointer to an unconstrained array type may be 21318converted to and from System.Address. Such usage is common in Ada 83 21319programs, but note that Ada.Address_To_Access_Conversions is the 21320preferred method of performing such conversions in Ada 95 and Ada 2005. 21321Neither 21322unchecked conversion nor Ada.Address_To_Access_Conversions should be 21323used in conjunction with pointers to unconstrained objects, since 21324the bounds information cannot be handled correctly in this case. 21325 21326@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 21327 21328This generic package allows explicit freeing of storage previously 21329allocated by use of an allocator. 21330 21331@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 21332 21333This package is similar to @code{Ada.Text_IO}, except that the external 21334file supports wide character representations, and the internal types are 21335@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21336and @code{String}. The corresponding set of nested packages and child 21337packages are defined. 21338 21339@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 21340 21341This package is similar to @code{Ada.Text_IO}, except that the external 21342file supports wide character representations, and the internal types are 21343@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21344and @code{String}. The corresponding set of nested packages and child 21345packages are defined. 21346@end table 21347 21348For packages in Interfaces and System, all the RM defined packages are 21349available in GNAT, see the Ada 2012 RM for full details. 21350 21351@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 21352@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{29a}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{29b} 21353@chapter The Implementation of Standard I/O 21354 21355 21356GNAT implements all the required input-output facilities described in 21357A.6 through A.14. These sections of the Ada Reference Manual describe the 21358required behavior of these packages from the Ada point of view, and if 21359you are writing a portable Ada program that does not need to know the 21360exact manner in which Ada maps to the outside world when it comes to 21361reading or writing external files, then you do not need to read this 21362chapter. As long as your files are all regular files (not pipes or 21363devices), and as long as you write and read the files only from Ada, the 21364description in the Ada Reference Manual is sufficient. 21365 21366However, if you want to do input-output to pipes or other devices, such 21367as the keyboard or screen, or if the files you are dealing with are 21368either generated by some other language, or to be read by some other 21369language, then you need to know more about the details of how the GNAT 21370implementation of these input-output facilities behaves. 21371 21372In this chapter we give a detailed description of exactly how GNAT 21373interfaces to the file system. As always, the sources of the system are 21374available to you for answering questions at an even more detailed level, 21375but for most purposes the information in this chapter will suffice. 21376 21377Another reason that you may need to know more about how input-output is 21378implemented arises when you have a program written in mixed languages 21379where, for example, files are shared between the C and Ada sections of 21380the same program. GNAT provides some additional facilities, in the form 21381of additional child library packages, that facilitate this sharing, and 21382these additional facilities are also described in this chapter. 21383 21384@menu 21385* Standard I/O Packages:: 21386* FORM Strings:: 21387* Direct_IO:: 21388* Sequential_IO:: 21389* Text_IO:: 21390* Wide_Text_IO:: 21391* Wide_Wide_Text_IO:: 21392* Stream_IO:: 21393* Text Translation:: 21394* Shared Files:: 21395* Filenames encoding:: 21396* File content encoding:: 21397* Open Modes:: 21398* Operations on C Streams:: 21399* Interfacing to C Streams:: 21400 21401@end menu 21402 21403@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 21404@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{29c}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{29d} 21405@section Standard I/O Packages 21406 21407 21408The Standard I/O packages described in Annex A for 21409 21410 21411@itemize * 21412 21413@item 21414Ada.Text_IO 21415 21416@item 21417Ada.Text_IO.Complex_IO 21418 21419@item 21420Ada.Text_IO.Text_Streams 21421 21422@item 21423Ada.Wide_Text_IO 21424 21425@item 21426Ada.Wide_Text_IO.Complex_IO 21427 21428@item 21429Ada.Wide_Text_IO.Text_Streams 21430 21431@item 21432Ada.Wide_Wide_Text_IO 21433 21434@item 21435Ada.Wide_Wide_Text_IO.Complex_IO 21436 21437@item 21438Ada.Wide_Wide_Text_IO.Text_Streams 21439 21440@item 21441Ada.Stream_IO 21442 21443@item 21444Ada.Sequential_IO 21445 21446@item 21447Ada.Direct_IO 21448@end itemize 21449 21450are implemented using the C 21451library streams facility; where 21452 21453 21454@itemize * 21455 21456@item 21457All files are opened using @code{fopen}. 21458 21459@item 21460All input/output operations use @code{fread}/@cite{fwrite}. 21461@end itemize 21462 21463There is no internal buffering of any kind at the Ada library level. The only 21464buffering is that provided at the system level in the implementation of the 21465library routines that support streams. This facilitates shared use of these 21466streams by mixed language programs. Note though that system level buffering is 21467explicitly enabled at elaboration of the standard I/O packages and that can 21468have an impact on mixed language programs, in particular those using I/O before 21469calling the Ada elaboration routine (e.g., adainit). It is recommended to call 21470the Ada elaboration routine before performing any I/O or when impractical, 21471flush the common I/O streams and in particular Standard_Output before 21472elaborating the Ada code. 21473 21474@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 21475@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{29e}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{29f} 21476@section FORM Strings 21477 21478 21479The format of a FORM string in GNAT is: 21480 21481@example 21482"keyword=value,keyword=value,...,keyword=value" 21483@end example 21484 21485where letters may be in upper or lower case, and there are no spaces 21486between values. The order of the entries is not important. Currently 21487the following keywords defined. 21488 21489@example 21490TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 21491SHARED=[YES|NO] 21492WCEM=[n|h|u|s|e|8|b] 21493ENCODING=[UTF8|8BITS] 21494@end example 21495 21496The use of these parameters is described later in this section. If an 21497unrecognized keyword appears in a form string, it is silently ignored 21498and not considered invalid. 21499 21500@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 21501@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a0}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a1} 21502@section Direct_IO 21503 21504 21505Direct_IO can only be instantiated for definite types. This is a 21506restriction of the Ada language, which means that the records are fixed 21507length (the length being determined by @code{type'Size}, rounded 21508up to the next storage unit boundary if necessary). 21509 21510The records of a Direct_IO file are simply written to the file in index 21511sequence, with the first record starting at offset zero, and subsequent 21512records following. There is no control information of any kind. For 21513example, if 32-bit integers are being written, each record takes 215144-bytes, so the record at index @code{K} starts at offset 21515(@code{K}-1)*4. 21516 21517There is no limit on the size of Direct_IO files, they are expanded as 21518necessary to accommodate whatever records are written to the file. 21519 21520@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 21521@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a3} 21522@section Sequential_IO 21523 21524 21525Sequential_IO may be instantiated with either a definite (constrained) 21526or indefinite (unconstrained) type. 21527 21528For the definite type case, the elements written to the file are simply 21529the memory images of the data values with no control information of any 21530kind. The resulting file should be read using the same type, no validity 21531checking is performed on input. 21532 21533For the indefinite type case, the elements written consist of two 21534parts. First is the size of the data item, written as the memory image 21535of a @code{Interfaces.C.size_t} value, followed by the memory image of 21536the data value. The resulting file can only be read using the same 21537(unconstrained) type. Normal assignment checks are performed on these 21538read operations, and if these checks fail, @code{Data_Error} is 21539raised. In particular, in the array case, the lengths must match, and in 21540the variant record case, if the variable for a particular read operation 21541is constrained, the discriminants must match. 21542 21543Note that it is not possible to use Sequential_IO to write variable 21544length array items, and then read the data back into different length 21545arrays. For example, the following will raise @code{Data_Error}: 21546 21547@example 21548package IO is new Sequential_IO (String); 21549F : IO.File_Type; 21550S : String (1..4); 21551... 21552IO.Create (F) 21553IO.Write (F, "hello!") 21554IO.Reset (F, Mode=>In_File); 21555IO.Read (F, S); 21556Put_Line (S); 21557@end example 21558 21559On some Ada implementations, this will print @code{hell}, but the program is 21560clearly incorrect, since there is only one element in the file, and that 21561element is the string @code{hello!}. 21562 21563In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 21564using Stream_IO, and this is the preferred mechanism. In particular, the 21565above program fragment rewritten to use Stream_IO will work correctly. 21566 21567@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 21568@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2a4}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2a5} 21569@section Text_IO 21570 21571 21572Text_IO files consist of a stream of characters containing the following 21573special control characters: 21574 21575@example 21576LF (line feed, 16#0A#) Line Mark 21577FF (form feed, 16#0C#) Page Mark 21578@end example 21579 21580A canonical Text_IO file is defined as one in which the following 21581conditions are met: 21582 21583 21584@itemize * 21585 21586@item 21587The character @code{LF} is used only as a line mark, i.e., to mark the end 21588of the line. 21589 21590@item 21591The character @code{FF} is used only as a page mark, i.e., to mark the 21592end of a page and consequently can appear only immediately following a 21593@code{LF} (line mark) character. 21594 21595@item 21596The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} 21597(line mark, page mark). In the former case, the page mark is implicitly 21598assumed to be present. 21599@end itemize 21600 21601A file written using Text_IO will be in canonical form provided that no 21602explicit @code{LF} or @code{FF} characters are written using @code{Put} 21603or @code{Put_Line}. There will be no @code{FF} character at the end of 21604the file unless an explicit @code{New_Page} operation was performed 21605before closing the file. 21606 21607A canonical Text_IO file that is a regular file (i.e., not a device or a 21608pipe) can be read using any of the routines in Text_IO. The 21609semantics in this case will be exactly as defined in the Ada Reference 21610Manual, and all the routines in Text_IO are fully implemented. 21611 21612A text file that does not meet the requirements for a canonical Text_IO 21613file has one of the following: 21614 21615 21616@itemize * 21617 21618@item 21619The file contains @code{FF} characters not immediately following a 21620@code{LF} character. 21621 21622@item 21623The file contains @code{LF} or @code{FF} characters written by 21624@code{Put} or @code{Put_Line}, which are not logically considered to be 21625line marks or page marks. 21626 21627@item 21628The file ends in a character other than @code{LF} or @code{FF}, 21629i.e., there is no explicit line mark or page mark at the end of the file. 21630@end itemize 21631 21632Text_IO can be used to read such non-standard text files but subprograms 21633to do with line or page numbers do not have defined meanings. In 21634particular, a @code{FF} character that does not follow a @code{LF} 21635character may or may not be treated as a page mark from the point of 21636view of page and line numbering. Every @code{LF} character is considered 21637to end a line, and there is an implied @code{LF} character at the end of 21638the file. 21639 21640@menu 21641* Stream Pointer Positioning:: 21642* Reading and Writing Non-Regular Files:: 21643* Get_Immediate:: 21644* Treating Text_IO Files as Streams:: 21645* Text_IO Extensions:: 21646* Text_IO Facilities for Unbounded Strings:: 21647 21648@end menu 21649 21650@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21651@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2a6}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2a7} 21652@subsection Stream Pointer Positioning 21653 21654 21655@code{Ada.Text_IO} has a definition of current position for a file that 21656is being read. No internal buffering occurs in Text_IO, and usually the 21657physical position in the stream used to implement the file corresponds 21658to this logical position defined by Text_IO. There are two exceptions: 21659 21660 21661@itemize * 21662 21663@item 21664After a call to @code{End_Of_Page} that returns @code{True}, the stream 21665is positioned past the @code{LF} (line mark) that precedes the page 21666mark. Text_IO maintains an internal flag so that subsequent read 21667operations properly handle the logical position which is unchanged by 21668the @code{End_Of_Page} call. 21669 21670@item 21671After a call to @code{End_Of_File} that returns @code{True}, if the 21672Text_IO file was positioned before the line mark at the end of file 21673before the call, then the logical position is unchanged, but the stream 21674is physically positioned right at the end of file (past the line mark, 21675and past a possible page mark following the line mark. Again Text_IO 21676maintains internal flags so that subsequent read operations properly 21677handle the logical position. 21678@end itemize 21679 21680These discrepancies have no effect on the observable behavior of 21681Text_IO, but if a single Ada stream is shared between a C program and 21682Ada program, or shared (using @code{shared=yes} in the form string) 21683between two Ada files, then the difference may be observable in some 21684situations. 21685 21686@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21687@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2a8}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2a9} 21688@subsection Reading and Writing Non-Regular Files 21689 21690 21691A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21692can be used for reading and writing. Writing is not affected and the 21693sequence of characters output is identical to the normal file case, but 21694for reading, the behavior of Text_IO is modified to avoid undesirable 21695look-ahead as follows: 21696 21697An input file that is not a regular file is considered to have no page 21698marks. Any @code{Ascii.FF} characters (the character normally used for a 21699page mark) appearing in the file are considered to be data 21700characters. In particular: 21701 21702 21703@itemize * 21704 21705@item 21706@code{Get_Line} and @code{Skip_Line} do not test for a page mark 21707following a line mark. If a page mark appears, it will be treated as a 21708data character. 21709 21710@item 21711This avoids the need to wait for an extra character to be typed or 21712entered from the pipe to complete one of these operations. 21713 21714@item 21715@code{End_Of_Page} always returns @code{False} 21716 21717@item 21718@code{End_Of_File} will return @code{False} if there is a page mark at 21719the end of the file. 21720@end itemize 21721 21722Output to non-regular files is the same as for regular files. Page marks 21723may be written to non-regular files using @code{New_Page}, but as noted 21724above they will not be treated as page marks on input if the output is 21725piped to another Ada program. 21726 21727Another important discrepancy when reading non-regular files is that the end 21728of file indication is not 'sticky'. If an end of file is entered, e.g., by 21729pressing the @code{EOT} key, 21730then end of file 21731is signaled once (i.e., the test @code{End_Of_File} 21732will yield @code{True}, or a read will 21733raise @code{End_Error}), but then reading can resume 21734to read data past that end of 21735file indication, until another end of file indication is entered. 21736 21737@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21738@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2aa}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2ab} 21739@subsection Get_Immediate 21740 21741 21742@geindex Get_Immediate 21743 21744Get_Immediate returns the next character (including control characters) 21745from the input file. In particular, Get_Immediate will return LF or FF 21746characters used as line marks or page marks. Such operations leave the 21747file positioned past the control character, and it is thus not treated 21748as having its normal function. This means that page, line and column 21749counts after this kind of Get_Immediate call are set as though the mark 21750did not occur. In the case where a Get_Immediate leaves the file 21751positioned between the line mark and page mark (which is not normally 21752possible), it is undefined whether the FF character will be treated as a 21753page mark. 21754 21755@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21756@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2ac}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2ad} 21757@subsection Treating Text_IO Files as Streams 21758 21759 21760@geindex Stream files 21761 21762The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated 21763as a stream. Data written to a @code{Text_IO} file in this stream mode is 21764binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 2176516#0C# (@code{FF}), the resulting file may have non-standard 21766format. Similarly if read operations are used to read from a Text_IO 21767file treated as a stream, then @code{LF} and @code{FF} characters may be 21768skipped and the effect is similar to that described above for 21769@code{Get_Immediate}. 21770 21771@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 21772@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2af} 21773@subsection Text_IO Extensions 21774 21775 21776@geindex Text_IO extensions 21777 21778A package GNAT.IO_Aux in the GNAT library provides some useful extensions 21779to the standard @code{Text_IO} package: 21780 21781 21782@itemize * 21783 21784@item 21785function File_Exists (Name : String) return Boolean; 21786Determines if a file of the given name exists. 21787 21788@item 21789function Get_Line return String; 21790Reads a string from the standard input file. The value returned is exactly 21791the length of the line that was read. 21792 21793@item 21794function Get_Line (File : Ada.Text_IO.File_Type) return String; 21795Similar, except that the parameter File specifies the file from which 21796the string is to be read. 21797@end itemize 21798 21799@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 21800@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b0}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b1} 21801@subsection Text_IO Facilities for Unbounded Strings 21802 21803 21804@geindex Text_IO for unbounded strings 21805 21806@geindex Unbounded_String 21807@geindex Text_IO operations 21808 21809The package @code{Ada.Strings.Unbounded.Text_IO} 21810in library files @code{a-suteio.ads/adb} contains some GNAT-specific 21811subprograms useful for Text_IO operations on unbounded strings: 21812 21813 21814@itemize * 21815 21816@item 21817function Get_Line (File : File_Type) return Unbounded_String; 21818Reads a line from the specified file 21819and returns the result as an unbounded string. 21820 21821@item 21822procedure Put (File : File_Type; U : Unbounded_String); 21823Writes the value of the given unbounded string to the specified file 21824Similar to the effect of 21825@code{Put (To_String (U))} except that an extra copy is avoided. 21826 21827@item 21828procedure Put_Line (File : File_Type; U : Unbounded_String); 21829Writes the value of the given unbounded string to the specified file, 21830followed by a @code{New_Line}. 21831Similar to the effect of @code{Put_Line (To_String (U))} except 21832that an extra copy is avoided. 21833@end itemize 21834 21835In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 21836and is optional. If the parameter is omitted, then the standard input or 21837output file is referenced as appropriate. 21838 21839The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 21840files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 21841@code{Wide_Text_IO} functionality for unbounded wide strings. 21842 21843The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 21844files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 21845@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 21846 21847@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 21848@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2b2}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b3} 21849@section Wide_Text_IO 21850 21851 21852@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 21853both input and output files may contain special sequences that represent 21854wide character values. The encoding scheme for a given file may be 21855specified using a FORM parameter: 21856 21857@example 21858WCEM=`x` 21859@end example 21860 21861as part of the FORM string (WCEM = wide character encoding method), 21862where @code{x} is one of the following characters 21863 21864 21865@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21866@headitem 21867 21868Character 21869 21870@tab 21871 21872Encoding 21873 21874@item 21875 21876@emph{h} 21877 21878@tab 21879 21880Hex ESC encoding 21881 21882@item 21883 21884@emph{u} 21885 21886@tab 21887 21888Upper half encoding 21889 21890@item 21891 21892@emph{s} 21893 21894@tab 21895 21896Shift-JIS encoding 21897 21898@item 21899 21900@emph{e} 21901 21902@tab 21903 21904EUC Encoding 21905 21906@item 21907 21908@emph{8} 21909 21910@tab 21911 21912UTF-8 encoding 21913 21914@item 21915 21916@emph{b} 21917 21918@tab 21919 21920Brackets encoding 21921 21922@end multitable 21923 21924 21925The encoding methods match those that 21926can be used in a source 21927program, but there is no requirement that the encoding method used for 21928the source program be the same as the encoding method used for files, 21929and different files may use different encoding methods. 21930 21931The default encoding method for the standard files, and for opened files 21932for which no WCEM parameter is given in the FORM string matches the 21933wide character encoding specified for the main program (the default 21934being brackets encoding if no coding method was specified with -gnatW). 21935 21936 21937@table @asis 21938 21939@item @emph{Hex Coding} 21940 21941In this encoding, a wide character is represented by a five character 21942sequence: 21943@end table 21944 21945@example 21946ESC a b c d 21947@end example 21948 21949 21950@quotation 21951 21952where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 21953characters (using upper case letters) of the wide character code. For 21954example, ESC A345 is used to represent the wide character with code 2195516#A345#. This scheme is compatible with use of the full 21956@code{Wide_Character} set. 21957@end quotation 21958 21959 21960@table @asis 21961 21962@item @emph{Upper Half Coding} 21963 21964The wide character with encoding 16#abcd#, where the upper bit is on 21965(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2196616#cd#. The second byte may never be a format control character, but is 21967not required to be in the upper half. This method can be also used for 21968shift-JIS or EUC where the internal coding matches the external coding. 21969 21970@item @emph{Shift JIS Coding} 21971 21972A wide character is represented by a two character sequence 16#ab# and 2197316#cd#, with the restrictions described for upper half encoding as 21974described above. The internal character code is the corresponding JIS 21975character according to the standard algorithm for Shift-JIS 21976conversion. Only characters defined in the JIS code set table can be 21977used with this encoding method. 21978 21979@item @emph{EUC Coding} 21980 21981A wide character is represented by a two character sequence 16#ab# and 2198216#cd#, with both characters being in the upper half. The internal 21983character code is the corresponding JIS character according to the EUC 21984encoding algorithm. Only characters defined in the JIS code set table 21985can be used with this encoding method. 21986 21987@item @emph{UTF-8 Coding} 21988 21989A wide character is represented using 21990UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2199110646-1/Am.2. Depending on the character value, the representation 21992is a one, two, or three byte sequence: 21993@end table 21994 21995@example 2199616#0000#-16#007f#: 2#0xxxxxxx# 2199716#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2199816#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 21999@end example 22000 22001 22002@quotation 22003 22004where the @code{xxx} bits correspond to the left-padded bits of the 2200516-bit character value. Note that all lower half ASCII characters 22006are represented as ASCII bytes and all upper half characters and 22007other wide characters are represented as sequences of upper-half 22008(The full UTF-8 scheme allows for encoding 31-bit characters as 220096-byte sequences, but in this implementation, all UTF-8 sequences 22010of four or more bytes length will raise a Constraint_Error, as 22011will all invalid UTF-8 sequences.) 22012@end quotation 22013 22014 22015@table @asis 22016 22017@item @emph{Brackets Coding} 22018 22019In this encoding, a wide character is represented by the following eight 22020character sequence: 22021@end table 22022 22023@example 22024[ " a b c d " ] 22025@end example 22026 22027 22028@quotation 22029 22030where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 22031characters (using uppercase letters) of the wide character code. For 22032example, @code{["A345"]} is used to represent the wide character with code 22033@code{16#A345#}. 22034This scheme is compatible with use of the full Wide_Character set. 22035On input, brackets coding can also be used for upper half characters, 22036e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22037is only used for wide characters with a code greater than @code{16#FF#}. 22038 22039Note that brackets coding is not normally used in the context of 22040Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 22041a portable way of encoding source files. In the context of Wide_Text_IO 22042or Wide_Wide_Text_IO, it can only be used if the file does not contain 22043any instance of the left bracket character other than to encode wide 22044character values using the brackets encoding method. In practice it is 22045expected that some standard wide character encoding method such 22046as UTF-8 will be used for text input output. 22047 22048If brackets notation is used, then any occurrence of a left bracket 22049in the input file which is not the start of a valid wide character 22050sequence will cause Constraint_Error to be raised. It is possible to 22051encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 22052input will interpret this as a left bracket. 22053 22054However, when a left bracket is output, it will be output as a left bracket 22055and not as ["5B"]. We make this decision because for normal use of 22056Wide_Text_IO for outputting messages, it is unpleasant to clobber left 22057brackets. For example, if we write: 22058 22059@example 22060Put_Line ("Start of output [first run]"); 22061@end example 22062 22063we really do not want to have the left bracket in this message clobbered so 22064that the output reads: 22065@end quotation 22066 22067@example 22068Start of output ["5B"]first run] 22069@end example 22070 22071 22072@quotation 22073 22074In practice brackets encoding is reasonably useful for normal Put_Line use 22075since we won't get confused between left brackets and wide character 22076sequences in the output. But for input, or when files are written out 22077and read back in, it really makes better sense to use one of the standard 22078encoding methods such as UTF-8. 22079@end quotation 22080 22081For the coding schemes other than UTF-8, Hex, or Brackets encoding, 22082not all wide character 22083values can be represented. An attempt to output a character that cannot 22084be represented using the encoding scheme for the file causes 22085Constraint_Error to be raised. An invalid wide character sequence on 22086input also causes Constraint_Error to be raised. 22087 22088@menu 22089* Stream Pointer Positioning: Stream Pointer Positioning<2>. 22090* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 22091 22092@end menu 22093 22094@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 22095@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2b4}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2b5} 22096@subsection Stream Pointer Positioning 22097 22098 22099@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22100of stream pointer positioning (@ref{2a5,,Text_IO}). There is one additional 22101case: 22102 22103If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 22104normal lower ASCII set (i.e., a character in the range: 22105 22106@example 22107Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 22108@end example 22109 22110then although the logical position of the file pointer is unchanged by 22111the @code{Look_Ahead} call, the stream is physically positioned past the 22112wide character sequence. Again this is to avoid the need for buffering 22113or backup, and all @code{Wide_Text_IO} routines check the internal 22114indication that this situation has occurred so that this is not visible 22115to a normal program using @code{Wide_Text_IO}. However, this discrepancy 22116can be observed if the wide text file shares a stream with another file. 22117 22118@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 22119@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2b6}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2b7} 22120@subsection Reading and Writing Non-Regular Files 22121 22122 22123As in the case of Text_IO, when a non-regular file is read, it is 22124assumed that the file contains no page marks (any form characters are 22125treated as data characters), and @code{End_Of_Page} always returns 22126@code{False}. Similarly, the end of file indication is not sticky, so 22127it is possible to read beyond an end of file. 22128 22129@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 22130@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2b8}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2b9} 22131@section Wide_Wide_Text_IO 22132 22133 22134@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 22135both input and output files may contain special sequences that represent 22136wide wide character values. The encoding scheme for a given file may be 22137specified using a FORM parameter: 22138 22139@example 22140WCEM=`x` 22141@end example 22142 22143as part of the FORM string (WCEM = wide character encoding method), 22144where @code{x} is one of the following characters 22145 22146 22147@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 22148@headitem 22149 22150Character 22151 22152@tab 22153 22154Encoding 22155 22156@item 22157 22158@emph{h} 22159 22160@tab 22161 22162Hex ESC encoding 22163 22164@item 22165 22166@emph{u} 22167 22168@tab 22169 22170Upper half encoding 22171 22172@item 22173 22174@emph{s} 22175 22176@tab 22177 22178Shift-JIS encoding 22179 22180@item 22181 22182@emph{e} 22183 22184@tab 22185 22186EUC Encoding 22187 22188@item 22189 22190@emph{8} 22191 22192@tab 22193 22194UTF-8 encoding 22195 22196@item 22197 22198@emph{b} 22199 22200@tab 22201 22202Brackets encoding 22203 22204@end multitable 22205 22206 22207The encoding methods match those that 22208can be used in a source 22209program, but there is no requirement that the encoding method used for 22210the source program be the same as the encoding method used for files, 22211and different files may use different encoding methods. 22212 22213The default encoding method for the standard files, and for opened files 22214for which no WCEM parameter is given in the FORM string matches the 22215wide character encoding specified for the main program (the default 22216being brackets encoding if no coding method was specified with -gnatW). 22217 22218 22219@table @asis 22220 22221@item @emph{UTF-8 Coding} 22222 22223A wide character is represented using 22224UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2222510646-1/Am.2. Depending on the character value, the representation 22226is a one, two, three, or four byte sequence: 22227@end table 22228 22229@example 2223016#000000#-16#00007f#: 2#0xxxxxxx# 2223116#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2223216#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2223316#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 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 2224021-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 22243characters. 22244@end quotation 22245 22246 22247@table @asis 22248 22249@item @emph{Brackets Coding} 22250 22251In this encoding, a wide wide character is represented by the following eight 22252character sequence if is in wide character range 22253@end table 22254 22255@example 22256[ " a b c d " ] 22257@end example 22258 22259 22260@quotation 22261 22262and by the following ten character sequence if not 22263@end quotation 22264 22265@example 22266[ " a b c d e f " ] 22267@end example 22268 22269 22270@quotation 22271 22272where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 22273are the four or six hexadecimal 22274characters (using uppercase letters) of the wide wide character code. For 22275example, @code{["01A345"]} is used to represent the wide wide character 22276with code @code{16#01A345#}. 22277 22278This scheme is compatible with use of the full Wide_Wide_Character set. 22279On input, brackets coding can also be used for upper half characters, 22280e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22281is only used for wide characters with a code greater than @code{16#FF#}. 22282@end quotation 22283 22284If is also possible to use the other Wide_Character encoding methods, 22285such as Shift-JIS, but the other schemes cannot support the full range 22286of wide wide characters. 22287An attempt to output a character that cannot 22288be represented using the encoding scheme for the file causes 22289Constraint_Error to be raised. An invalid wide character sequence on 22290input also causes Constraint_Error to be raised. 22291 22292@menu 22293* Stream Pointer Positioning: Stream Pointer Positioning<3>. 22294* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 22295 22296@end menu 22297 22298@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 22299@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2ba}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2bb} 22300@subsection Stream Pointer Positioning 22301 22302 22303@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22304of stream pointer positioning (@ref{2a5,,Text_IO}). There is one additional 22305case: 22306 22307If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 22308normal lower ASCII set (i.e., a character in the range: 22309 22310@example 22311Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 22312@end example 22313 22314then although the logical position of the file pointer is unchanged by 22315the @code{Look_Ahead} call, the stream is physically positioned past the 22316wide character sequence. Again this is to avoid the need for buffering 22317or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 22318indication that this situation has occurred so that this is not visible 22319to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 22320can be observed if the wide text file shares a stream with another file. 22321 22322@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 22323@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2bc}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2bd} 22324@subsection Reading and Writing Non-Regular Files 22325 22326 22327As in the case of Text_IO, when a non-regular file is read, it is 22328assumed that the file contains no page marks (any form characters are 22329treated as data characters), and @code{End_Of_Page} always returns 22330@code{False}. Similarly, the end of file indication is not sticky, so 22331it is possible to read beyond an end of file. 22332 22333@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 22334@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2be}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2bf} 22335@section Stream_IO 22336 22337 22338A stream file is a sequence of bytes, where individual elements are 22339written to the file as described in the Ada Reference Manual. The type 22340@code{Stream_Element} is simply a byte. There are two ways to read or 22341write a stream file. 22342 22343 22344@itemize * 22345 22346@item 22347The operations @code{Read} and @code{Write} directly read or write a 22348sequence of stream elements with no control information. 22349 22350@item 22351The stream attributes applied to a stream file transfer data in the 22352manner described for stream attributes. 22353@end itemize 22354 22355@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 22356@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c0}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c1} 22357@section Text Translation 22358 22359 22360@code{Text_Translation=xxx} may be used as the Form parameter 22361passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 22362has no effect on Unix systems. Possible values are: 22363 22364 22365@itemize * 22366 22367@item 22368@code{Yes} or @code{Text} is the default, which means to 22369translate LF to/from CR/LF on Windows systems. 22370 22371@code{No} disables this translation; i.e. it 22372uses binary mode. For output files, @code{Text_Translation=No} 22373may be used to create Unix-style files on 22374Windows. 22375 22376@item 22377@code{wtext} translation enabled in Unicode mode. 22378(corresponds to _O_WTEXT). 22379 22380@item 22381@code{u8text} translation enabled in Unicode UTF-8 mode. 22382(corresponds to O_U8TEXT). 22383 22384@item 22385@code{u16text} translation enabled in Unicode UTF-16 22386mode. (corresponds to_O_U16TEXT). 22387@end itemize 22388 22389@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 22390@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c2}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2c3} 22391@section Shared Files 22392 22393 22394Section A.14 of the Ada Reference Manual allows implementations to 22395provide a wide variety of behavior if an attempt is made to access the 22396same external file with two or more internal files. 22397 22398To provide a full range of functionality, while at the same time 22399minimizing the problems of portability caused by this implementation 22400dependence, GNAT handles file sharing as follows: 22401 22402 22403@itemize * 22404 22405@item 22406In the absence of a @code{shared=xxx} form parameter, an attempt 22407to open two or more files with the same full name is considered an error 22408and is not supported. The exception @code{Use_Error} will be 22409raised. Note that a file that is not explicitly closed by the program 22410remains open until the program terminates. 22411 22412@item 22413If the form parameter @code{shared=no} appears in the form string, the 22414file can be opened or created with its own separate stream identifier, 22415regardless of whether other files sharing the same external file are 22416opened. The exact effect depends on how the C stream routines handle 22417multiple accesses to the same external files using separate streams. 22418 22419@item 22420If the form parameter @code{shared=yes} appears in the form string for 22421each of two or more files opened using the same full name, the same 22422stream is shared between these files, and the semantics are as described 22423in Ada Reference Manual, Section A.14. 22424@end itemize 22425 22426When a program that opens multiple files with the same name is ported 22427from another Ada compiler to GNAT, the effect will be that 22428@code{Use_Error} is raised. 22429 22430The documentation of the original compiler and the documentation of the 22431program should then be examined to determine if file sharing was 22432expected, and @code{shared=xxx} parameters added to @code{Open} 22433and @code{Create} calls as required. 22434 22435When a program is ported from GNAT to some other Ada compiler, no 22436special attention is required unless the @code{shared=xxx} form 22437parameter is used in the program. In this case, you must examine the 22438documentation of the new compiler to see if it supports the required 22439file sharing semantics, and form strings modified appropriately. Of 22440course it may be the case that the program cannot be ported if the 22441target compiler does not support the required functionality. The best 22442approach in writing portable code is to avoid file sharing (and hence 22443the use of the @code{shared=xxx} parameter in the form string) 22444completely. 22445 22446One common use of file sharing in Ada 83 is the use of instantiations of 22447Sequential_IO on the same file with different types, to achieve 22448heterogeneous input-output. Although this approach will work in GNAT if 22449@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 22450for this purpose (using the stream attributes) 22451 22452@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 22453@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2c4}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2c5} 22454@section Filenames encoding 22455 22456 22457An encoding form parameter can be used to specify the filename 22458encoding @code{encoding=xxx}. 22459 22460 22461@itemize * 22462 22463@item 22464If the form parameter @code{encoding=utf8} appears in the form string, the 22465filename must be encoded in UTF-8. 22466 22467@item 22468If the form parameter @code{encoding=8bits} appears in the form 22469string, the filename must be a standard 8bits string. 22470@end itemize 22471 22472In the absence of a @code{encoding=xxx} form parameter, the 22473encoding is controlled by the @code{GNAT_CODE_PAGE} environment 22474variable. And if not set @code{utf8} is assumed. 22475 22476 22477@table @asis 22478 22479@item @emph{CP_ACP} 22480 22481The current system Windows ANSI code page. 22482 22483@item @emph{CP_UTF8} 22484 22485UTF-8 encoding 22486@end table 22487 22488This encoding form parameter is only supported on the Windows 22489platform. On the other Operating Systems the run-time is supporting 22490UTF-8 natively. 22491 22492@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 22493@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2c6}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2c7} 22494@section File content encoding 22495 22496 22497For text files it is possible to specify the encoding to use. This is 22498controlled by the by the @code{GNAT_CCS_ENCODING} environment 22499variable. And if not set @code{TEXT} is assumed. 22500 22501The possible values are those supported on Windows: 22502 22503 22504@table @asis 22505 22506@item @emph{TEXT} 22507 22508Translated text mode 22509 22510@item @emph{WTEXT} 22511 22512Translated unicode encoding 22513 22514@item @emph{U16TEXT} 22515 22516Unicode 16-bit encoding 22517 22518@item @emph{U8TEXT} 22519 22520Unicode 8-bit encoding 22521@end table 22522 22523This encoding is only supported on the Windows platform. 22524 22525@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 22526@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2c8}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2c9} 22527@section Open Modes 22528 22529 22530@code{Open} and @code{Create} calls result in a call to @code{fopen} 22531using the mode shown in the following table: 22532 22533 22534@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 22535@headitem 22536 22537@code{Open} and @code{Create} Call Modes 22538 22539@tab 22540 22541@tab 22542 22543@item 22544 22545@tab 22546 22547@strong{OPEN} 22548 22549@tab 22550 22551@strong{CREATE} 22552 22553@item 22554 22555Append_File 22556 22557@tab 22558 22559"r+" 22560 22561@tab 22562 22563"w+" 22564 22565@item 22566 22567In_File 22568 22569@tab 22570 22571"r" 22572 22573@tab 22574 22575"w+" 22576 22577@item 22578 22579Out_File (Direct_IO) 22580 22581@tab 22582 22583"r+" 22584 22585@tab 22586 22587"w" 22588 22589@item 22590 22591Out_File (all other cases) 22592 22593@tab 22594 22595"w" 22596 22597@tab 22598 22599"w" 22600 22601@item 22602 22603Inout_File 22604 22605@tab 22606 22607"r+" 22608 22609@tab 22610 22611"w+" 22612 22613@end multitable 22614 22615 22616If text file translation is required, then either @code{b} or @code{t} 22617is added to the mode, depending on the setting of Text. Text file 22618translation refers to the mapping of CR/LF sequences in an external file 22619to LF characters internally. This mapping only occurs in DOS and 22620DOS-like systems, and is not relevant to other systems. 22621 22622A special case occurs with Stream_IO. As shown in the above table, the 22623file is initially opened in @code{r} or @code{w} mode for the 22624@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 22625subsequently requires switching from reading to writing or vice-versa, 22626then the file is reopened in @code{r+} mode to permit the required operation. 22627 22628@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22629@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2ca}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2cb} 22630@section Operations on C Streams 22631 22632 22633The package @code{Interfaces.C_Streams} provides an Ada program with direct 22634access to the C library functions for operations on C streams: 22635 22636@example 22637package Interfaces.C_Streams is 22638 -- Note: the reason we do not use the types that are in 22639 -- Interfaces.C is that we want to avoid dragging in the 22640 -- code in this unit if possible. 22641 subtype chars is System.Address; 22642 -- Pointer to null-terminated array of characters 22643 subtype FILEs is System.Address; 22644 -- Corresponds to the C type FILE* 22645 subtype voids is System.Address; 22646 -- Corresponds to the C type void* 22647 subtype int is Integer; 22648 subtype long is Long_Integer; 22649 -- Note: the above types are subtypes deliberately, and it 22650 -- is part of this spec that the above correspondences are 22651 -- guaranteed. This means that it is legitimate to, for 22652 -- example, use Integer instead of int. We provide these 22653 -- synonyms for clarity, but in some cases it may be 22654 -- convenient to use the underlying types (for example to 22655 -- avoid an unnecessary dependency of a spec on the spec 22656 -- of this unit). 22657 type size_t is mod 2 ** Standard'Address_Size; 22658 NULL_Stream : constant FILEs; 22659 -- Value returned (NULL in C) to indicate an 22660 -- fdopen/fopen/tmpfile error 22661 ---------------------------------- 22662 -- Constants Defined in stdio.h -- 22663 ---------------------------------- 22664 EOF : constant int; 22665 -- Used by a number of routines to indicate error or 22666 -- end of file 22667 IOFBF : constant int; 22668 IOLBF : constant int; 22669 IONBF : constant int; 22670 -- Used to indicate buffering mode for setvbuf call 22671 SEEK_CUR : constant int; 22672 SEEK_END : constant int; 22673 SEEK_SET : constant int; 22674 -- Used to indicate origin for fseek call 22675 function stdin return FILEs; 22676 function stdout return FILEs; 22677 function stderr return FILEs; 22678 -- Streams associated with standard files 22679 -------------------------- 22680 -- Standard C functions -- 22681 -------------------------- 22682 -- The functions selected below are ones that are 22683 -- available in UNIX (but not necessarily in ANSI C). 22684 -- These are very thin interfaces 22685 -- which copy exactly the C headers. For more 22686 -- documentation on these functions, see the Microsoft C 22687 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22688 -- ISBN 1-55615-225-6), which includes useful information 22689 -- on system compatibility. 22690 procedure clearerr (stream : FILEs); 22691 function fclose (stream : FILEs) return int; 22692 function fdopen (handle : int; mode : chars) return FILEs; 22693 function feof (stream : FILEs) return int; 22694 function ferror (stream : FILEs) return int; 22695 function fflush (stream : FILEs) return int; 22696 function fgetc (stream : FILEs) return int; 22697 function fgets (strng : chars; n : int; stream : FILEs) 22698 return chars; 22699 function fileno (stream : FILEs) return int; 22700 function fopen (filename : chars; Mode : chars) 22701 return FILEs; 22702 -- Note: to maintain target independence, use 22703 -- text_translation_required, a boolean variable defined in 22704 -- a-sysdep.c to deal with the target dependent text 22705 -- translation requirement. If this variable is set, 22706 -- then b/t should be appended to the standard mode 22707 -- argument to set the text translation mode off or on 22708 -- as required. 22709 function fputc (C : int; stream : FILEs) return int; 22710 function fputs (Strng : chars; Stream : FILEs) return int; 22711 function fread 22712 (buffer : voids; 22713 size : size_t; 22714 count : size_t; 22715 stream : FILEs) 22716 return size_t; 22717 function freopen 22718 (filename : chars; 22719 mode : chars; 22720 stream : FILEs) 22721 return FILEs; 22722 function fseek 22723 (stream : FILEs; 22724 offset : long; 22725 origin : int) 22726 return int; 22727 function ftell (stream : FILEs) return long; 22728 function fwrite 22729 (buffer : voids; 22730 size : size_t; 22731 count : size_t; 22732 stream : FILEs) 22733 return size_t; 22734 function isatty (handle : int) return int; 22735 procedure mktemp (template : chars); 22736 -- The return value (which is just a pointer to template) 22737 -- is discarded 22738 procedure rewind (stream : FILEs); 22739 function rmtmp return int; 22740 function setvbuf 22741 (stream : FILEs; 22742 buffer : chars; 22743 mode : int; 22744 size : size_t) 22745 return int; 22746 22747 function tmpfile return FILEs; 22748 function ungetc (c : int; stream : FILEs) return int; 22749 function unlink (filename : chars) return int; 22750 --------------------- 22751 -- Extra functions -- 22752 --------------------- 22753 -- These functions supply slightly thicker bindings than 22754 -- those above. They are derived from functions in the 22755 -- C Run-Time Library, but may do a bit more work than 22756 -- just directly calling one of the Library functions. 22757 function is_regular_file (handle : int) return int; 22758 -- Tests if given handle is for a regular file (result 1) 22759 -- or for a non-regular file (pipe or device, result 0). 22760 --------------------------------- 22761 -- Control of Text/Binary Mode -- 22762 --------------------------------- 22763 -- If text_translation_required is true, then the following 22764 -- functions may be used to dynamically switch a file from 22765 -- binary to text mode or vice versa. These functions have 22766 -- no effect if text_translation_required is false (i.e., in 22767 -- normal UNIX mode). Use fileno to get a stream handle. 22768 procedure set_binary_mode (handle : int); 22769 procedure set_text_mode (handle : int); 22770 ---------------------------- 22771 -- Full Path Name support -- 22772 ---------------------------- 22773 procedure full_name (nam : chars; buffer : chars); 22774 -- Given a NUL terminated string representing a file 22775 -- name, returns in buffer a NUL terminated string 22776 -- representing the full path name for the file name. 22777 -- On systems where it is relevant the drive is also 22778 -- part of the full path name. It is the responsibility 22779 -- of the caller to pass an actual parameter for buffer 22780 -- that is big enough for any full path name. Use 22781 -- max_path_len given below as the size of buffer. 22782 max_path_len : integer; 22783 -- Maximum length of an allowable full path name on the 22784 -- system, including a terminating NUL character. 22785end Interfaces.C_Streams; 22786@end example 22787 22788@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 22789@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2cc}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2cd} 22790@section Interfacing to C Streams 22791 22792 22793The packages in this section permit interfacing Ada files to C Stream 22794operations. 22795 22796@example 22797with Interfaces.C_Streams; 22798package Ada.Sequential_IO.C_Streams is 22799 function C_Stream (F : File_Type) 22800 return Interfaces.C_Streams.FILEs; 22801 procedure Open 22802 (File : in out File_Type; 22803 Mode : in File_Mode; 22804 C_Stream : in Interfaces.C_Streams.FILEs; 22805 Form : in String := ""); 22806end Ada.Sequential_IO.C_Streams; 22807 22808 with Interfaces.C_Streams; 22809 package Ada.Direct_IO.C_Streams is 22810 function C_Stream (F : File_Type) 22811 return Interfaces.C_Streams.FILEs; 22812 procedure Open 22813 (File : in out File_Type; 22814 Mode : in File_Mode; 22815 C_Stream : in Interfaces.C_Streams.FILEs; 22816 Form : in String := ""); 22817 end Ada.Direct_IO.C_Streams; 22818 22819 with Interfaces.C_Streams; 22820 package Ada.Text_IO.C_Streams is 22821 function C_Stream (F : File_Type) 22822 return Interfaces.C_Streams.FILEs; 22823 procedure Open 22824 (File : in out File_Type; 22825 Mode : in File_Mode; 22826 C_Stream : in Interfaces.C_Streams.FILEs; 22827 Form : in String := ""); 22828 end Ada.Text_IO.C_Streams; 22829 22830 with Interfaces.C_Streams; 22831 package Ada.Wide_Text_IO.C_Streams is 22832 function C_Stream (F : File_Type) 22833 return Interfaces.C_Streams.FILEs; 22834 procedure Open 22835 (File : in out File_Type; 22836 Mode : in File_Mode; 22837 C_Stream : in Interfaces.C_Streams.FILEs; 22838 Form : in String := ""); 22839end Ada.Wide_Text_IO.C_Streams; 22840 22841 with Interfaces.C_Streams; 22842 package Ada.Wide_Wide_Text_IO.C_Streams is 22843 function C_Stream (F : File_Type) 22844 return Interfaces.C_Streams.FILEs; 22845 procedure Open 22846 (File : in out File_Type; 22847 Mode : in File_Mode; 22848 C_Stream : in Interfaces.C_Streams.FILEs; 22849 Form : in String := ""); 22850end Ada.Wide_Wide_Text_IO.C_Streams; 22851 22852with Interfaces.C_Streams; 22853package Ada.Stream_IO.C_Streams is 22854 function C_Stream (F : File_Type) 22855 return Interfaces.C_Streams.FILEs; 22856 procedure Open 22857 (File : in out File_Type; 22858 Mode : in File_Mode; 22859 C_Stream : in Interfaces.C_Streams.FILEs; 22860 Form : in String := ""); 22861end Ada.Stream_IO.C_Streams; 22862@end example 22863 22864In each of these six packages, the @code{C_Stream} function obtains the 22865@code{FILE} pointer from a currently opened Ada file. It is then 22866possible to use the @code{Interfaces.C_Streams} package to operate on 22867this stream, or the stream can be passed to a C program which can 22868operate on it directly. Of course the program is responsible for 22869ensuring that only appropriate sequences of operations are executed. 22870 22871One particular use of relevance to an Ada program is that the 22872@code{setvbuf} function can be used to control the buffering of the 22873stream used by an Ada file. In the absence of such a call the standard 22874default buffering is used. 22875 22876The @code{Open} procedures in these packages open a file giving an 22877existing C Stream instead of a file name. Typically this stream is 22878imported from a C program, allowing an Ada file to operate on an 22879existing C file. 22880 22881@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 22882@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2ce}@anchor{gnat_rm/the_gnat_library id1}@anchor{2cf} 22883@chapter The GNAT Library 22884 22885 22886The GNAT library contains a number of general and special purpose packages. 22887It represents functionality that the GNAT developers have found useful, and 22888which is made available to GNAT users. The packages described here are fully 22889supported, and upwards compatibility will be maintained in future releases, 22890so you can use these facilities with the confidence that the same functionality 22891will be available in future releases. 22892 22893The chapter here simply gives a brief summary of the facilities available. 22894The full documentation is found in the spec file for the package. The full 22895sources of these library packages, including both spec and body, are provided 22896with all GNAT releases. For example, to find out the full specifications of 22897the SPITBOL pattern matching capability, including a full tutorial and 22898extensive examples, look in the @code{g-spipat.ads} file in the library. 22899 22900For each entry here, the package name (as it would appear in a @code{with} 22901clause) is given, followed by the name of the corresponding spec file in 22902parentheses. The packages are children in four hierarchies, @code{Ada}, 22903@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 22904GNAT-specific hierarchy. 22905 22906Note that an application program should only use packages in one of these 22907four hierarchies if the package is defined in the Ada Reference Manual, 22908or is listed in this section of the GNAT Programmers Reference Manual. 22909All other units should be considered internal implementation units and 22910should not be directly @code{with}ed by application code. The use of 22911a @code{with} clause that references one of these internal implementation 22912units makes an application potentially dependent on changes in versions 22913of GNAT, and will generate a warning message. 22914 22915@menu 22916* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 22917* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 22918* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 22919* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 22920* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 22921* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 22922* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 22923* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 22924* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 22925* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 22926* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 22927* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 22928* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 22929* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 22930* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 22931* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 22932* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 22933* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 22934* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 22935* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 22936* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 22937* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 22938* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 22939* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 22940* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 22941* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 22942* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 22943* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 22944* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 22945* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 22946* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 22947* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 22948* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 22949* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 22950* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 22951* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 22952* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 22953* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 22954* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 22955* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 22956* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 22957* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 22958* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 22959* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 22960* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 22961* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 22962* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 22963* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 22964* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 22965* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 22966* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 22967* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 22968* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 22969* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 22970* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 22971* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 22972* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 22973* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 22974* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 22975* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 22976* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 22977* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 22978* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 22979* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 22980* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 22981* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 22982* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 22983* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 22984* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 22985* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 22986* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 22987* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 22988* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 22989* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 22990* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 22991* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 22992* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 22993* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 22994* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 22995* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 22996* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 22997* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 22998* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 22999* GNAT.IO (g-io.ads): GNAT IO g-io ads. 23000* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 23001* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 23002* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 23003* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 23004* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 23005* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 23006* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 23007* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 23008* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 23009* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 23010* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 23011* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 23012* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 23013* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 23014* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 23015* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 23016* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 23017* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 23018* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 23019* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 23020* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 23021* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 23022* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 23023* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 23024* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 23025* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 23026* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 23027* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 23028* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 23029* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 23030* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 23031* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 23032* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 23033* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 23034* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 23035* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 23036* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 23037* GNAT.Table (g-table.ads): GNAT Table g-table ads. 23038* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 23039* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 23040* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 23041* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 23042* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 23043* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 23044* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 23045* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 23046* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 23047* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 23048* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 23049* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 23050* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 23051* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 23052* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 23053* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 23054* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 23055* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 23056* System.Assertions (s-assert.ads): System Assertions s-assert ads. 23057* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 23058* System.Memory (s-memory.ads): System Memory s-memory ads. 23059* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 23060* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 23061* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 23062* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 23063* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 23064* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 23065* System.Rident (s-rident.ads): System Rident s-rident ads. 23066* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 23067* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 23068* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 23069* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 23070 23071@end menu 23072 23073@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 23074@anchor{gnat_rm/the_gnat_library id2}@anchor{2d0}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d1} 23075@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 23076 23077 23078@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 23079 23080@geindex Latin_9 constants for Character 23081 23082This child of @code{Ada.Characters} 23083provides a set of definitions corresponding to those in the 23084RM-defined package @code{Ada.Characters.Latin_1} but with the 23085few modifications required for @code{Latin-9} 23086The provision of such a package 23087is specifically authorized by the Ada Reference Manual 23088(RM A.3.3(27)). 23089 23090@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 23091@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d2}@anchor{gnat_rm/the_gnat_library id3}@anchor{2d3} 23092@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 23093 23094 23095@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 23096 23097@geindex Latin_1 constants for Wide_Character 23098 23099This child of @code{Ada.Characters} 23100provides a set of definitions corresponding to those in the 23101RM-defined package @code{Ada.Characters.Latin_1} but with the 23102types of the constants being @code{Wide_Character} 23103instead of @code{Character}. The provision of such a package 23104is specifically authorized by the Ada Reference Manual 23105(RM A.3.3(27)). 23106 23107@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 23108@anchor{gnat_rm/the_gnat_library id4}@anchor{2d4}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2d5} 23109@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 23110 23111 23112@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 23113 23114@geindex Latin_9 constants for Wide_Character 23115 23116This child of @code{Ada.Characters} 23117provides a set of definitions corresponding to those in the 23118GNAT defined package @code{Ada.Characters.Latin_9} but with the 23119types of the constants being @code{Wide_Character} 23120instead of @code{Character}. The provision of such a package 23121is specifically authorized by the Ada Reference Manual 23122(RM A.3.3(27)). 23123 23124@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 23125@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2d6}@anchor{gnat_rm/the_gnat_library id5}@anchor{2d7} 23126@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 23127 23128 23129@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 23130 23131@geindex Latin_1 constants for Wide_Wide_Character 23132 23133This child of @code{Ada.Characters} 23134provides a set of definitions corresponding to those in the 23135RM-defined package @code{Ada.Characters.Latin_1} but with the 23136types of the constants being @code{Wide_Wide_Character} 23137instead of @code{Character}. The provision of such a package 23138is specifically authorized by the Ada Reference Manual 23139(RM A.3.3(27)). 23140 23141@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 23142@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2d8}@anchor{gnat_rm/the_gnat_library id6}@anchor{2d9} 23143@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 23144 23145 23146@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 23147 23148@geindex Latin_9 constants for Wide_Wide_Character 23149 23150This child of @code{Ada.Characters} 23151provides a set of definitions corresponding to those in the 23152GNAT defined package @code{Ada.Characters.Latin_9} but with the 23153types of the constants being @code{Wide_Wide_Character} 23154instead of @code{Character}. The provision of such a package 23155is specifically authorized by the Ada Reference Manual 23156(RM A.3.3(27)). 23157 23158@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 23159@anchor{gnat_rm/the_gnat_library id7}@anchor{2da}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2db} 23160@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 23161 23162 23163@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 23164 23165@geindex Formal container for doubly linked lists 23166 23167This child of @code{Ada.Containers} defines a modified version of the 23168Ada 2005 container for doubly linked lists, meant to facilitate formal 23169verification of code using such containers. The specification of this 23170unit is compatible with SPARK 2014. 23171 23172Note that although this container was designed with formal verification 23173in mind, it may well be generally useful in that it is a simplified more 23174efficient version than the one defined in the standard. In particular it 23175does not have the complex overhead required to detect cursor tampering. 23176 23177@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 23178@anchor{gnat_rm/the_gnat_library id8}@anchor{2dc}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2dd} 23179@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 23180 23181 23182@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 23183 23184@geindex Formal container for hashed maps 23185 23186This child of @code{Ada.Containers} defines a modified version of the 23187Ada 2005 container for hashed maps, meant to facilitate formal 23188verification of code using such containers. The specification of this 23189unit is compatible with SPARK 2014. 23190 23191Note that although this container was designed with formal verification 23192in mind, it may well be generally useful in that it is a simplified more 23193efficient version than the one defined in the standard. In particular it 23194does not have the complex overhead required to detect cursor tampering. 23195 23196@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 23197@anchor{gnat_rm/the_gnat_library id9}@anchor{2de}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2df} 23198@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 23199 23200 23201@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 23202 23203@geindex Formal container for hashed sets 23204 23205This child of @code{Ada.Containers} defines a modified version of the 23206Ada 2005 container for hashed sets, meant to facilitate formal 23207verification of code using such containers. The specification of this 23208unit is compatible with SPARK 2014. 23209 23210Note that although this container was designed with formal verification 23211in mind, it may well be generally useful in that it is a simplified more 23212efficient version than the one defined in the standard. In particular it 23213does not have the complex overhead required to detect cursor tampering. 23214 23215@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 23216@anchor{gnat_rm/the_gnat_library id10}@anchor{2e0}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e1} 23217@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 23218 23219 23220@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 23221 23222@geindex Formal container for ordered maps 23223 23224This child of @code{Ada.Containers} defines a modified version of the 23225Ada 2005 container for ordered maps, meant to facilitate formal 23226verification of code using such containers. The specification of this 23227unit is compatible with SPARK 2014. 23228 23229Note that although this container was designed with formal verification 23230in mind, it may well be generally useful in that it is a simplified more 23231efficient version than the one defined in the standard. In particular it 23232does not have the complex overhead required to detect cursor tampering. 23233 23234@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 23235@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e2}@anchor{gnat_rm/the_gnat_library id11}@anchor{2e3} 23236@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 23237 23238 23239@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 23240 23241@geindex Formal container for ordered sets 23242 23243This child of @code{Ada.Containers} defines a modified version of the 23244Ada 2005 container for ordered sets, meant to facilitate formal 23245verification of code using such containers. The specification of this 23246unit is compatible with SPARK 2014. 23247 23248Note that although this container was designed with formal verification 23249in mind, it may well be generally useful in that it is a simplified more 23250efficient version than the one defined in the standard. In particular it 23251does not have the complex overhead required to detect cursor tampering. 23252 23253@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 23254@anchor{gnat_rm/the_gnat_library id12}@anchor{2e4}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2e5} 23255@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 23256 23257 23258@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 23259 23260@geindex Formal container for vectors 23261 23262This child of @code{Ada.Containers} defines a modified version of the 23263Ada 2005 container for vectors, meant to facilitate formal 23264verification of code using such containers. The specification of this 23265unit is compatible with SPARK 2014. 23266 23267Note that although this container was designed with formal verification 23268in mind, it may well be generally useful in that it is a simplified more 23269efficient version than the one defined in the standard. In particular it 23270does not have the complex overhead required to detect cursor tampering. 23271 23272@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 23273@anchor{gnat_rm/the_gnat_library id13}@anchor{2e6}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2e7} 23274@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 23275 23276 23277@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 23278 23279@geindex Formal container for vectors 23280 23281This child of @code{Ada.Containers} defines a modified version of the 23282Ada 2005 container for vectors of indefinite elements, meant to 23283facilitate formal verification of code using such containers. The 23284specification of this unit is compatible with SPARK 2014. 23285 23286Note that although this container was designed with formal verification 23287in mind, it may well be generally useful in that it is a simplified more 23288efficient version than the one defined in the standard. In particular it 23289does not have the complex overhead required to detect cursor tampering. 23290 23291@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 23292@anchor{gnat_rm/the_gnat_library id14}@anchor{2e8}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2e9} 23293@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) 23294 23295 23296@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) 23297 23298@geindex Functional vectors 23299 23300This child of @code{Ada.Containers} defines immutable vectors. These 23301containers are unbounded and may contain indefinite elements. Furthermore, to 23302be usable in every context, they are neither controlled nor limited. As they 23303are functional, that is, no primitives are provided which would allow modifying 23304an existing container, these containers can still be used safely. 23305 23306Their API features functions creating new containers from existing ones. 23307As a consequence, these containers are highly inefficient. They are also 23308memory consuming, as the allocated memory is not reclaimed when the container 23309is no longer referenced. Thus, they should in general be used in ghost code 23310and annotations, so that they can be removed from the final executable. The 23311specification of this unit is compatible with SPARK 2014. 23312 23313@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 23314@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2ea}@anchor{gnat_rm/the_gnat_library id15}@anchor{2eb} 23315@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) 23316 23317 23318@geindex Ada.Containers.Functional_Sets (a-cofuse.ads) 23319 23320@geindex Functional sets 23321 23322This child of @code{Ada.Containers} defines immutable sets. These containers are 23323unbounded and may contain indefinite elements. Furthermore, to be usable in 23324every context, they are neither controlled nor limited. As they are functional, 23325that is, no primitives are provided which would allow modifying an existing 23326container, these containers can still be used safely. 23327 23328Their API features functions creating new containers from existing ones. 23329As a consequence, these containers are highly inefficient. They are also 23330memory consuming, as the allocated memory is not reclaimed when the container 23331is no longer referenced. Thus, they should in general be used in ghost code 23332and annotations, so that they can be removed from the final executable. The 23333specification of this unit is compatible with SPARK 2014. 23334 23335@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 23336@anchor{gnat_rm/the_gnat_library id16}@anchor{2ec}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2ed} 23337@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) 23338 23339 23340@geindex Ada.Containers.Functional_Maps (a-cofuma.ads) 23341 23342@geindex Functional maps 23343 23344This child of @code{Ada.Containers} defines immutable maps. These containers are 23345unbounded and may contain indefinite elements. Furthermore, to be usable in 23346every context, they are neither controlled nor limited. As they are functional, 23347that is, no primitives are provided which would allow modifying an existing 23348container, these containers can still be used safely. 23349 23350Their API features functions creating new containers from existing ones. 23351As a consequence, these containers are highly inefficient. They are also 23352memory consuming, as the allocated memory is not reclaimed when the container 23353is no longer referenced. Thus, they should in general be used in ghost code 23354and annotations, so that they can be removed from the final executable. The 23355specification of this unit is compatible with SPARK 2014. 23356 23357@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 23358@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2ee}@anchor{gnat_rm/the_gnat_library id17}@anchor{2ef} 23359@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 23360 23361 23362@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 23363 23364@geindex Formal container for vectors 23365 23366This child of @code{Ada.Containers} defines a modified version of 23367Indefinite_Holders that avoids heap allocation. 23368 23369@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 23370@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f0}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f1} 23371@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) 23372 23373 23374@geindex Ada.Command_Line.Environment (a-colien.ads) 23375 23376@geindex Environment entries 23377 23378This child of @code{Ada.Command_Line} 23379provides a mechanism for obtaining environment values on systems 23380where this concept makes sense. 23381 23382@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 23383@anchor{gnat_rm/the_gnat_library id19}@anchor{2f2}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f3} 23384@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) 23385 23386 23387@geindex Ada.Command_Line.Remove (a-colire.ads) 23388 23389@geindex Removing command line arguments 23390 23391@geindex Command line 23392@geindex argument removal 23393 23394This child of @code{Ada.Command_Line} 23395provides a mechanism for logically removing 23396arguments from the argument list. Once removed, an argument is not visible 23397to further calls on the subprograms in @code{Ada.Command_Line} will not 23398see the removed argument. 23399 23400@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 23401@anchor{gnat_rm/the_gnat_library id20}@anchor{2f4}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2f5} 23402@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 23403 23404 23405@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 23406 23407@geindex Response file for command line 23408 23409@geindex Command line 23410@geindex response file 23411 23412@geindex Command line 23413@geindex handling long command lines 23414 23415This child of @code{Ada.Command_Line} provides a mechanism facilities for 23416getting command line arguments from a text file, called a "response file". 23417Using a response file allow passing a set of arguments to an executable longer 23418than the maximum allowed by the system on the command line. 23419 23420@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 23421@anchor{gnat_rm/the_gnat_library id21}@anchor{2f6}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2f7} 23422@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 23423 23424 23425@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 23426 23427@geindex C Streams 23428@geindex Interfacing with Direct_IO 23429 23430This package provides subprograms that allow interfacing between 23431C streams and @code{Direct_IO}. The stream identifier can be 23432extracted from a file opened on the Ada side, and an Ada file 23433can be constructed from a stream opened on the C side. 23434 23435@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 23436@anchor{gnat_rm/the_gnat_library id22}@anchor{2f8}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f9} 23437@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 23438 23439 23440@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 23441 23442@geindex Null_Occurrence 23443@geindex testing for 23444 23445This child subprogram provides a way of testing for the null 23446exception occurrence (@code{Null_Occurrence}) without raising 23447an exception. 23448 23449@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 23450@anchor{gnat_rm/the_gnat_library id23}@anchor{2fa}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2fb} 23451@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 23452 23453 23454@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 23455 23456@geindex Null_Occurrence 23457@geindex testing for 23458 23459This child subprogram is used for handling otherwise unhandled 23460exceptions (hence the name last chance), and perform clean ups before 23461terminating the program. Note that this subprogram never returns. 23462 23463@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 23464@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2fc}@anchor{gnat_rm/the_gnat_library id24}@anchor{2fd} 23465@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 23466 23467 23468@geindex Ada.Exceptions.Traceback (a-exctra.ads) 23469 23470@geindex Traceback for Exception Occurrence 23471 23472This child package provides the subprogram (@code{Tracebacks}) to 23473give a traceback array of addresses based on an exception 23474occurrence. 23475 23476@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 23477@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2fe}@anchor{gnat_rm/the_gnat_library id25}@anchor{2ff} 23478@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 23479 23480 23481@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 23482 23483@geindex C Streams 23484@geindex Interfacing with Sequential_IO 23485 23486This package provides subprograms that allow interfacing between 23487C streams and @code{Sequential_IO}. The stream identifier can be 23488extracted from a file opened on the Ada side, and an Ada file 23489can be constructed from a stream opened on the C side. 23490 23491@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 23492@anchor{gnat_rm/the_gnat_library id26}@anchor{300}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{301} 23493@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 23494 23495 23496@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 23497 23498@geindex C Streams 23499@geindex Interfacing with Stream_IO 23500 23501This package provides subprograms that allow interfacing between 23502C streams and @code{Stream_IO}. The stream identifier can be 23503extracted from a file opened on the Ada side, and an Ada file 23504can be constructed from a stream opened on the C side. 23505 23506@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 23507@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{302}@anchor{gnat_rm/the_gnat_library id27}@anchor{303} 23508@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 23509 23510 23511@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 23512 23513@geindex Unbounded_String 23514@geindex IO support 23515 23516@geindex Text_IO 23517@geindex extensions for unbounded strings 23518 23519This package provides subprograms for Text_IO for unbounded 23520strings, avoiding the necessity for an intermediate operation 23521with ordinary strings. 23522 23523@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 23524@anchor{gnat_rm/the_gnat_library id28}@anchor{304}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{305} 23525@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 23526 23527 23528@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 23529 23530@geindex Unbounded_Wide_String 23531@geindex IO support 23532 23533@geindex Text_IO 23534@geindex extensions for unbounded wide strings 23535 23536This package provides subprograms for Text_IO for unbounded 23537wide strings, avoiding the necessity for an intermediate operation 23538with ordinary wide strings. 23539 23540@node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library 23541@anchor{gnat_rm/the_gnat_library id29}@anchor{306}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{307} 23542@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 23543 23544 23545@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 23546 23547@geindex Unbounded_Wide_Wide_String 23548@geindex IO support 23549 23550@geindex Text_IO 23551@geindex extensions for unbounded wide wide strings 23552 23553This package provides subprograms for Text_IO for unbounded 23554wide wide strings, avoiding the necessity for an intermediate operation 23555with ordinary wide wide strings. 23556 23557@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library 23558@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{308}@anchor{gnat_rm/the_gnat_library id30}@anchor{309} 23559@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 23560 23561 23562@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 23563 23564@geindex C Streams 23565@geindex Interfacing with `@w{`}Text_IO`@w{`} 23566 23567This package provides subprograms that allow interfacing between 23568C streams and @code{Text_IO}. The stream identifier can be 23569extracted from a file opened on the Ada side, and an Ada file 23570can be constructed from a stream opened on the C side. 23571 23572@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 23573@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{30a}@anchor{gnat_rm/the_gnat_library id31}@anchor{30b} 23574@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 23575 23576 23577@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 23578 23579@geindex Text_IO resetting standard files 23580 23581This procedure is used to reset the status of the standard files used 23582by Ada.Text_IO. This is useful in a situation (such as a restart in an 23583embedded application) where the status of the files may change during 23584execution (for example a standard input file may be redefined to be 23585interactive). 23586 23587@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 23588@anchor{gnat_rm/the_gnat_library id32}@anchor{30c}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{30d} 23589@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 23590 23591 23592@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 23593 23594@geindex Unicode categorization 23595@geindex Wide_Character 23596 23597This package provides subprograms that allow categorization of 23598Wide_Character values according to Unicode categories. 23599 23600@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 23601@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{30e}@anchor{gnat_rm/the_gnat_library id33}@anchor{30f} 23602@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 23603 23604 23605@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 23606 23607@geindex C Streams 23608@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} 23609 23610This package provides subprograms that allow interfacing between 23611C streams and @code{Wide_Text_IO}. The stream identifier can be 23612extracted from a file opened on the Ada side, and an Ada file 23613can be constructed from a stream opened on the C side. 23614 23615@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 23616@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{310}@anchor{gnat_rm/the_gnat_library id34}@anchor{311} 23617@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 23618 23619 23620@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 23621 23622@geindex Wide_Text_IO resetting standard files 23623 23624This procedure is used to reset the status of the standard files used 23625by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 23626embedded application) where the status of the files may change during 23627execution (for example a standard input file may be redefined to be 23628interactive). 23629 23630@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 23631@anchor{gnat_rm/the_gnat_library id35}@anchor{312}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{313} 23632@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 23633 23634 23635@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 23636 23637@geindex Unicode categorization 23638@geindex Wide_Wide_Character 23639 23640This package provides subprograms that allow categorization of 23641Wide_Wide_Character values according to Unicode categories. 23642 23643@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 23644@anchor{gnat_rm/the_gnat_library id36}@anchor{314}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{315} 23645@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 23646 23647 23648@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 23649 23650@geindex C Streams 23651@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} 23652 23653This package provides subprograms that allow interfacing between 23654C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 23655extracted from a file opened on the Ada side, and an Ada file 23656can be constructed from a stream opened on the C side. 23657 23658@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 23659@anchor{gnat_rm/the_gnat_library id37}@anchor{316}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{317} 23660@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 23661 23662 23663@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 23664 23665@geindex Wide_Wide_Text_IO resetting standard files 23666 23667This procedure is used to reset the status of the standard files used 23668by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 23669restart in an embedded application) where the status of the files may 23670change during execution (for example a standard input file may be 23671redefined to be interactive). 23672 23673@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 23674@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{318}@anchor{gnat_rm/the_gnat_library id38}@anchor{319} 23675@section @code{GNAT.Altivec} (@code{g-altive.ads}) 23676 23677 23678@geindex GNAT.Altivec (g-altive.ads) 23679 23680@geindex AltiVec 23681 23682This is the root package of the GNAT AltiVec binding. It provides 23683definitions of constants and types common to all the versions of the 23684binding. 23685 23686@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 23687@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{31a}@anchor{gnat_rm/the_gnat_library id39}@anchor{31b} 23688@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 23689 23690 23691@geindex GNAT.Altivec.Conversions (g-altcon.ads) 23692 23693@geindex AltiVec 23694 23695This package provides the Vector/View conversion routines. 23696 23697@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23698@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{31c}@anchor{gnat_rm/the_gnat_library id40}@anchor{31d} 23699@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23700 23701 23702@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23703 23704@geindex AltiVec 23705 23706This package exposes the Ada interface to the AltiVec operations on 23707vector objects. A soft emulation is included by default in the GNAT 23708library. The hard binding is provided as a separate package. This unit 23709is common to both bindings. 23710 23711@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 23712@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{31e}@anchor{gnat_rm/the_gnat_library id41}@anchor{31f} 23713@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23714 23715 23716@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23717 23718@geindex AltiVec 23719 23720This package exposes the various vector types part of the Ada binding 23721to AltiVec facilities. 23722 23723@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23724@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{320}@anchor{gnat_rm/the_gnat_library id42}@anchor{321} 23725@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23726 23727 23728@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23729 23730@geindex AltiVec 23731 23732This package provides public 'View' data types from/to which private 23733vector representations can be converted via 23734GNAT.Altivec.Conversions. This allows convenient access to individual 23735vector elements and provides a simple way to initialize vector 23736objects. 23737 23738@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23739@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{322}@anchor{gnat_rm/the_gnat_library id43}@anchor{323} 23740@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) 23741 23742 23743@geindex GNAT.Array_Split (g-arrspl.ads) 23744 23745@geindex Array splitter 23746 23747Useful array-manipulation routines: given a set of separators, split 23748an array wherever the separators appear, and provide direct access 23749to the resulting slices. 23750 23751@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 23752@anchor{gnat_rm/the_gnat_library id44}@anchor{324}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{325} 23753@section @code{GNAT.AWK} (@code{g-awk.ads}) 23754 23755 23756@geindex GNAT.AWK (g-awk.ads) 23757 23758@geindex Parsing 23759 23760@geindex AWK 23761 23762Provides AWK-like parsing functions, with an easy interface for parsing one 23763or more files containing formatted data. The file is viewed as a database 23764where each record is a line and a field is a data element in this line. 23765 23766@node GNAT Bind_Environment g-binenv ads,GNAT Bounded_Buffers g-boubuf ads,GNAT AWK g-awk ads,The GNAT Library 23767@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{326}@anchor{gnat_rm/the_gnat_library id45}@anchor{327} 23768@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) 23769 23770 23771@geindex GNAT.Bind_Environment (g-binenv.ads) 23772 23773@geindex Bind environment 23774 23775Provides access to key=value associations captured at bind time. 23776These associations can be specified using the @code{-V} binder command 23777line switch. 23778 23779@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 23780@anchor{gnat_rm/the_gnat_library id46}@anchor{328}@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{329} 23781@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 23782 23783 23784@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 23785 23786@geindex Parsing 23787 23788@geindex Bounded Buffers 23789 23790Provides a concurrent generic bounded buffer abstraction. Instances are 23791useful directly or as parts of the implementations of other abstractions, 23792such as mailboxes. 23793 23794@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 23795@anchor{gnat_rm/the_gnat_library id47}@anchor{32a}@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{32b} 23796@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 23797 23798 23799@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 23800 23801@geindex Parsing 23802 23803@geindex Mailboxes 23804 23805Provides a thread-safe asynchronous intertask mailbox communication facility. 23806 23807@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 23808@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{32c}@anchor{gnat_rm/the_gnat_library id48}@anchor{32d} 23809@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 23810 23811 23812@geindex GNAT.Bubble_Sort (g-bubsor.ads) 23813 23814@geindex Sorting 23815 23816@geindex Bubble sort 23817 23818Provides a general implementation of bubble sort usable for sorting arbitrary 23819data items. Exchange and comparison procedures are provided by passing 23820access-to-procedure values. 23821 23822@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 23823@anchor{gnat_rm/the_gnat_library id49}@anchor{32e}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{32f} 23824@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 23825 23826 23827@geindex GNAT.Bubble_Sort_A (g-busora.ads) 23828 23829@geindex Sorting 23830 23831@geindex Bubble sort 23832 23833Provides a general implementation of bubble sort usable for sorting arbitrary 23834data items. Move and comparison procedures are provided by passing 23835access-to-procedure values. This is an older version, retained for 23836compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 23837 23838@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 23839@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{330}@anchor{gnat_rm/the_gnat_library id50}@anchor{331} 23840@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 23841 23842 23843@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 23844 23845@geindex Sorting 23846 23847@geindex Bubble sort 23848 23849Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 23850are provided as generic parameters, this improves efficiency, especially 23851if the procedures can be inlined, at the expense of duplicating code for 23852multiple instantiations. 23853 23854@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 23855@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{332}@anchor{gnat_rm/the_gnat_library id51}@anchor{333} 23856@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 23857 23858 23859@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 23860 23861@geindex UTF-8 representation 23862 23863@geindex Wide characte representations 23864 23865Provides a routine which given a string, reads the start of the string to 23866see whether it is one of the standard byte order marks (BOM's) which signal 23867the encoding of the string. The routine includes detection of special XML 23868sequences for various UCS input formats. 23869 23870@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 23871@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{334}@anchor{gnat_rm/the_gnat_library id52}@anchor{335} 23872@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 23873 23874 23875@geindex GNAT.Byte_Swapping (g-bytswa.ads) 23876 23877@geindex Byte swapping 23878 23879@geindex Endianness 23880 23881General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 23882Machine-specific implementations are available in some cases. 23883 23884@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 23885@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{336}@anchor{gnat_rm/the_gnat_library id53}@anchor{337} 23886@section @code{GNAT.Calendar} (@code{g-calend.ads}) 23887 23888 23889@geindex GNAT.Calendar (g-calend.ads) 23890 23891@geindex Calendar 23892 23893Extends the facilities provided by @code{Ada.Calendar} to include handling 23894of days of the week, an extended @code{Split} and @code{Time_Of} capability. 23895Also provides conversion of @code{Ada.Calendar.Time} values to and from the 23896C @code{timeval} format. 23897 23898@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 23899@anchor{gnat_rm/the_gnat_library id54}@anchor{338}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{339} 23900@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 23901 23902 23903@geindex Calendar 23904 23905@geindex Time 23906 23907@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 23908 23909@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 23910@anchor{gnat_rm/the_gnat_library id55}@anchor{33a}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{33b} 23911@section @code{GNAT.CRC32} (@code{g-crc32.ads}) 23912 23913 23914@geindex GNAT.CRC32 (g-crc32.ads) 23915 23916@geindex CRC32 23917 23918@geindex Cyclic Redundancy Check 23919 23920This package implements the CRC-32 algorithm. For a full description 23921of this algorithm see 23922@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 23923@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 23924Aug. 1988. Sarwate, D.V. 23925 23926@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 23927@anchor{gnat_rm/the_gnat_library id56}@anchor{33c}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{33d} 23928@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) 23929 23930 23931@geindex GNAT.Case_Util (g-casuti.ads) 23932 23933@geindex Casing utilities 23934 23935@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) 23936 23937A set of simple routines for handling upper and lower casing of strings 23938without the overhead of the full casing tables 23939in @code{Ada.Characters.Handling}. 23940 23941@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 23942@anchor{gnat_rm/the_gnat_library id57}@anchor{33e}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{33f} 23943@section @code{GNAT.CGI} (@code{g-cgi.ads}) 23944 23945 23946@geindex GNAT.CGI (g-cgi.ads) 23947 23948@geindex CGI (Common Gateway Interface) 23949 23950This is a package for interfacing a GNAT program with a Web server via the 23951Common Gateway Interface (CGI). Basically this package parses the CGI 23952parameters, which are a set of key/value pairs sent by the Web server. It 23953builds a table whose index is the key and provides some services to deal 23954with this table. 23955 23956@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 23957@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{340}@anchor{gnat_rm/the_gnat_library id58}@anchor{341} 23958@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 23959 23960 23961@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 23962 23963@geindex CGI (Common Gateway Interface) cookie support 23964 23965@geindex Cookie support in CGI 23966 23967This is a package to interface a GNAT program with a Web server via the 23968Common Gateway Interface (CGI). It exports services to deal with Web 23969cookies (piece of information kept in the Web client software). 23970 23971@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 23972@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{342}@anchor{gnat_rm/the_gnat_library id59}@anchor{343} 23973@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 23974 23975 23976@geindex GNAT.CGI.Debug (g-cgideb.ads) 23977 23978@geindex CGI (Common Gateway Interface) debugging 23979 23980This is a package to help debugging CGI (Common Gateway Interface) 23981programs written in Ada. 23982 23983@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 23984@anchor{gnat_rm/the_gnat_library id60}@anchor{344}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{345} 23985@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) 23986 23987 23988@geindex GNAT.Command_Line (g-comlin.ads) 23989 23990@geindex Command line 23991 23992Provides a high level interface to @code{Ada.Command_Line} facilities, 23993including the ability to scan for named switches with optional parameters 23994and expand file names using wild card notations. 23995 23996@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 23997@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{346}@anchor{gnat_rm/the_gnat_library id61}@anchor{347} 23998@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) 23999 24000 24001@geindex GNAT.Compiler_Version (g-comver.ads) 24002 24003@geindex Compiler Version 24004 24005@geindex Version 24006@geindex of compiler 24007 24008Provides a routine for obtaining the version of the compiler used to 24009compile the program. More accurately this is the version of the binder 24010used to bind the program (this will normally be the same as the version 24011of the compiler if a consistent tool set is used to compile all units 24012of a partition). 24013 24014@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 24015@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{348}@anchor{gnat_rm/the_gnat_library id62}@anchor{349} 24016@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 24017 24018 24019@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 24020 24021@geindex Interrupt 24022 24023Provides a simple interface to handle Ctrl-C keyboard events. 24024 24025@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 24026@anchor{gnat_rm/the_gnat_library id63}@anchor{34a}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{34b} 24027@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) 24028 24029 24030@geindex GNAT.Current_Exception (g-curexc.ads) 24031 24032@geindex Current exception 24033 24034@geindex Exception retrieval 24035 24036Provides access to information on the current exception that has been raised 24037without the need for using the Ada 95 / Ada 2005 exception choice parameter 24038specification syntax. 24039This is particularly useful in simulating typical facilities for 24040obtaining information about exceptions provided by Ada 83 compilers. 24041 24042@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 24043@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id64}@anchor{34d} 24044@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 24045 24046 24047@geindex GNAT.Debug_Pools (g-debpoo.ads) 24048 24049@geindex Debugging 24050 24051@geindex Debug pools 24052 24053@geindex Memory corruption debugging 24054 24055Provide a debugging storage pools that helps tracking memory corruption 24056problems. 24057See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}. 24058 24059@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 24060@anchor{gnat_rm/the_gnat_library id65}@anchor{34e}@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{34f} 24061@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 24062 24063 24064@geindex GNAT.Debug_Utilities (g-debuti.ads) 24065 24066@geindex Debugging 24067 24068Provides a few useful utilities for debugging purposes, including conversion 24069to and from string images of address values. Supports both C and Ada formats 24070for hexadecimal literals. 24071 24072@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 24073@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{350}@anchor{gnat_rm/the_gnat_library id66}@anchor{351} 24074@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) 24075 24076 24077@geindex GNAT.Decode_String (g-decstr.ads) 24078 24079@geindex Decoding strings 24080 24081@geindex String decoding 24082 24083@geindex Wide character encoding 24084 24085@geindex UTF-8 24086 24087@geindex Unicode 24088 24089A generic package providing routines for decoding wide character and wide wide 24090character strings encoded as sequences of 8-bit characters using a specified 24091encoding method. Includes validation routines, and also routines for stepping 24092to next or previous encoded character in an encoded string. 24093Useful in conjunction with Unicode character coding. Note there is a 24094preinstantiation for UTF-8. See next entry. 24095 24096@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 24097@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{352}@anchor{gnat_rm/the_gnat_library id67}@anchor{353} 24098@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 24099 24100 24101@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 24102 24103@geindex Decoding strings 24104 24105@geindex Decoding UTF-8 strings 24106 24107@geindex UTF-8 string decoding 24108 24109@geindex Wide character decoding 24110 24111@geindex UTF-8 24112 24113@geindex Unicode 24114 24115A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 24116 24117@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 24118@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{354}@anchor{gnat_rm/the_gnat_library id68}@anchor{355} 24119@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) 24120 24121 24122@geindex GNAT.Directory_Operations (g-dirope.ads) 24123 24124@geindex Directory operations 24125 24126Provides a set of routines for manipulating directories, including changing 24127the current directory, making new directories, and scanning the files in a 24128directory. 24129 24130@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 24131@anchor{gnat_rm/the_gnat_library id69}@anchor{356}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{357} 24132@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 24133 24134 24135@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 24136 24137@geindex Directory operations iteration 24138 24139A child unit of GNAT.Directory_Operations providing additional operations 24140for iterating through directories. 24141 24142@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 24143@anchor{gnat_rm/the_gnat_library id70}@anchor{358}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{359} 24144@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 24145 24146 24147@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 24148 24149@geindex Hash tables 24150 24151A generic implementation of hash tables that can be used to hash arbitrary 24152data. Provided in two forms, a simple form with built in hash functions, 24153and a more complex form in which the hash function is supplied. 24154 24155This package provides a facility similar to that of @code{GNAT.HTable}, 24156except that this package declares a type that can be used to define 24157dynamic instances of the hash table, while an instantiation of 24158@code{GNAT.HTable} creates a single instance of the hash table. 24159 24160@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 24161@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{35a}@anchor{gnat_rm/the_gnat_library id71}@anchor{35b} 24162@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 24163 24164 24165@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 24166 24167@geindex Table implementation 24168 24169@geindex Arrays 24170@geindex extendable 24171 24172A generic package providing a single dimension array abstraction where the 24173length of the array can be dynamically modified. 24174 24175This package provides a facility similar to that of @code{GNAT.Table}, 24176except that this package declares a type that can be used to define 24177dynamic instances of the table, while an instantiation of 24178@code{GNAT.Table} creates a single instance of the table type. 24179 24180@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 24181@anchor{gnat_rm/the_gnat_library id72}@anchor{35c}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{35d} 24182@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) 24183 24184 24185@geindex GNAT.Encode_String (g-encstr.ads) 24186 24187@geindex Encoding strings 24188 24189@geindex String encoding 24190 24191@geindex Wide character encoding 24192 24193@geindex UTF-8 24194 24195@geindex Unicode 24196 24197A generic package providing routines for encoding wide character and wide 24198wide character strings as sequences of 8-bit characters using a specified 24199encoding method. Useful in conjunction with Unicode character coding. 24200Note there is a preinstantiation for UTF-8. See next entry. 24201 24202@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 24203@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{35e}@anchor{gnat_rm/the_gnat_library id73}@anchor{35f} 24204@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 24205 24206 24207@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 24208 24209@geindex Encoding strings 24210 24211@geindex Encoding UTF-8 strings 24212 24213@geindex UTF-8 string encoding 24214 24215@geindex Wide character encoding 24216 24217@geindex UTF-8 24218 24219@geindex Unicode 24220 24221A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 24222 24223@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 24224@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{360}@anchor{gnat_rm/the_gnat_library id74}@anchor{361} 24225@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) 24226 24227 24228@geindex GNAT.Exception_Actions (g-excact.ads) 24229 24230@geindex Exception actions 24231 24232Provides callbacks when an exception is raised. Callbacks can be registered 24233for specific exceptions, or when any exception is raised. This 24234can be used for instance to force a core dump to ease debugging. 24235 24236@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library 24237@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{362}@anchor{gnat_rm/the_gnat_library id75}@anchor{363} 24238@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) 24239 24240 24241@geindex GNAT.Exception_Traces (g-exctra.ads) 24242 24243@geindex Exception traces 24244 24245@geindex Debugging 24246 24247Provides an interface allowing to control automatic output upon exception 24248occurrences. 24249 24250@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 24251@anchor{gnat_rm/the_gnat_library id76}@anchor{364}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{365} 24252@section @code{GNAT.Exceptions} (@code{g-except.ads}) 24253 24254 24255@geindex GNAT.Exceptions (g-except.ads) 24256 24257@geindex Exceptions 24258@geindex Pure 24259 24260@geindex Pure packages 24261@geindex exceptions 24262 24263Normally it is not possible to raise an exception with 24264a message from a subprogram in a pure package, since the 24265necessary types and subprograms are in @code{Ada.Exceptions} 24266which is not a pure unit. @code{GNAT.Exceptions} provides a 24267facility for getting around this limitation for a few 24268predefined exceptions, and for example allow raising 24269@code{Constraint_Error} with a message from a pure subprogram. 24270 24271@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library 24272@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{366}@anchor{gnat_rm/the_gnat_library id77}@anchor{367} 24273@section @code{GNAT.Expect} (@code{g-expect.ads}) 24274 24275 24276@geindex GNAT.Expect (g-expect.ads) 24277 24278Provides a set of subprograms similar to what is available 24279with the standard Tcl Expect tool. 24280It allows you to easily spawn and communicate with an external process. 24281You can send commands or inputs to the process, and compare the output 24282with some expected regular expression. Currently @code{GNAT.Expect} 24283is implemented on all native GNAT ports. 24284It is not implemented for cross ports, and in particular is not 24285implemented for VxWorks or LynxOS. 24286 24287@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 24288@anchor{gnat_rm/the_gnat_library id78}@anchor{368}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{369} 24289@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) 24290 24291 24292@geindex GNAT.Expect.TTY (g-exptty.ads) 24293 24294As GNAT.Expect but using pseudo-terminal. 24295Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 24296ports. It is not implemented for cross ports, and 24297in particular is not implemented for VxWorks or LynxOS. 24298 24299@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 24300@anchor{gnat_rm/the_gnat_library id79}@anchor{36a}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{36b} 24301@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) 24302 24303 24304@geindex GNAT.Float_Control (g-flocon.ads) 24305 24306@geindex Floating-Point Processor 24307 24308Provides an interface for resetting the floating-point processor into the 24309mode required for correct semantic operation in Ada. Some third party 24310library calls may cause this mode to be modified, and the Reset procedure 24311in this package can be used to reestablish the required mode. 24312 24313@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 24314@anchor{gnat_rm/the_gnat_library id80}@anchor{36c}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{36d} 24315@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) 24316 24317 24318@geindex GNAT.Formatted_String (g-forstr.ads) 24319 24320@geindex Formatted String 24321 24322Provides support for C/C++ printf() formatted strings. The format is 24323copied from the printf() routine and should therefore gives identical 24324output. Some generic routines are provided to be able to use types 24325derived from Integer, Float or enumerations as values for the 24326formatted string. 24327 24328@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 24329@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{36e}@anchor{gnat_rm/the_gnat_library id81}@anchor{36f} 24330@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) 24331 24332 24333@geindex GNAT.Heap_Sort (g-heasor.ads) 24334 24335@geindex Sorting 24336 24337Provides a general implementation of heap sort usable for sorting arbitrary 24338data items. Exchange and comparison procedures are provided by passing 24339access-to-procedure values. The algorithm used is a modified heap sort 24340that performs approximately N*log(N) comparisons in the worst case. 24341 24342@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 24343@anchor{gnat_rm/the_gnat_library id82}@anchor{370}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{371} 24344@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 24345 24346 24347@geindex GNAT.Heap_Sort_A (g-hesora.ads) 24348 24349@geindex Sorting 24350 24351Provides a general implementation of heap sort usable for sorting arbitrary 24352data items. Move and comparison procedures are provided by passing 24353access-to-procedure values. The algorithm used is a modified heap sort 24354that performs approximately N*log(N) comparisons in the worst case. 24355This differs from @code{GNAT.Heap_Sort} in having a less convenient 24356interface, but may be slightly more efficient. 24357 24358@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 24359@anchor{gnat_rm/the_gnat_library id83}@anchor{372}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{373} 24360@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 24361 24362 24363@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 24364 24365@geindex Sorting 24366 24367Similar to @code{Heap_Sort_A} except that the move and sorting procedures 24368are provided as generic parameters, this improves efficiency, especially 24369if the procedures can be inlined, at the expense of duplicating code for 24370multiple instantiations. 24371 24372@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 24373@anchor{gnat_rm/the_gnat_library id84}@anchor{374}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{375} 24374@section @code{GNAT.HTable} (@code{g-htable.ads}) 24375 24376 24377@geindex GNAT.HTable (g-htable.ads) 24378 24379@geindex Hash tables 24380 24381A generic implementation of hash tables that can be used to hash arbitrary 24382data. Provides two approaches, one a simple static approach, and the other 24383allowing arbitrary dynamic hash tables. 24384 24385@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 24386@anchor{gnat_rm/the_gnat_library id85}@anchor{376}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{377} 24387@section @code{GNAT.IO} (@code{g-io.ads}) 24388 24389 24390@geindex GNAT.IO (g-io.ads) 24391 24392@geindex Simple I/O 24393 24394@geindex Input/Output facilities 24395 24396A simple preelaborable input-output package that provides a subset of 24397simple Text_IO functions for reading characters and strings from 24398Standard_Input, and writing characters, strings and integers to either 24399Standard_Output or Standard_Error. 24400 24401@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 24402@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{378}@anchor{gnat_rm/the_gnat_library id86}@anchor{379} 24403@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) 24404 24405 24406@geindex GNAT.IO_Aux (g-io_aux.ads) 24407 24408@geindex Text_IO 24409 24410@geindex Input/Output facilities 24411 24412Provides some auxiliary functions for use with Text_IO, including a test 24413for whether a file exists, and functions for reading a line of text. 24414 24415@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 24416@anchor{gnat_rm/the_gnat_library id87}@anchor{37a}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{37b} 24417@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) 24418 24419 24420@geindex GNAT.Lock_Files (g-locfil.ads) 24421 24422@geindex File locking 24423 24424@geindex Locking using files 24425 24426Provides a general interface for using files as locks. Can be used for 24427providing program level synchronization. 24428 24429@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 24430@anchor{gnat_rm/the_gnat_library id88}@anchor{37c}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{37d} 24431@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 24432 24433 24434@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 24435 24436@geindex Random number generation 24437 24438The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 24439a modified version of the Blum-Blum-Shub generator. 24440 24441@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 24442@anchor{gnat_rm/the_gnat_library id89}@anchor{37e}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{37f} 24443@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 24444 24445 24446@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 24447 24448@geindex Random number generation 24449 24450The original implementation of @code{Ada.Numerics.Float_Random}. Uses 24451a modified version of the Blum-Blum-Shub generator. 24452 24453@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 24454@anchor{gnat_rm/the_gnat_library id90}@anchor{380}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{381} 24455@section @code{GNAT.MD5} (@code{g-md5.ads}) 24456 24457 24458@geindex GNAT.MD5 (g-md5.ads) 24459 24460@geindex Message Digest MD5 24461 24462Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 24463the HMAC-MD5 message authentication function as described in RFC 2104 and 24464FIPS PUB 198. 24465 24466@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 24467@anchor{gnat_rm/the_gnat_library id91}@anchor{382}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{383} 24468@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) 24469 24470 24471@geindex GNAT.Memory_Dump (g-memdum.ads) 24472 24473@geindex Dump Memory 24474 24475Provides a convenient routine for dumping raw memory to either the 24476standard output or standard error files. Uses GNAT.IO for actual 24477output. 24478 24479@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 24480@anchor{gnat_rm/the_gnat_library id92}@anchor{384}@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{385} 24481@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 24482 24483 24484@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 24485 24486@geindex Exception 24487@geindex obtaining most recent 24488 24489Provides access to the most recently raised exception. Can be used for 24490various logging purposes, including duplicating functionality of some 24491Ada 83 implementation dependent extensions. 24492 24493@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 24494@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id93}@anchor{387} 24495@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) 24496 24497 24498@geindex GNAT.OS_Lib (g-os_lib.ads) 24499 24500@geindex Operating System interface 24501 24502@geindex Spawn capability 24503 24504Provides a range of target independent operating system interface functions, 24505including time/date management, file operations, subprocess management, 24506including a portable spawn procedure, and access to environment variables 24507and error return codes. 24508 24509@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 24510@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id94}@anchor{389} 24511@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 24512 24513 24514@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 24515 24516@geindex Hash functions 24517 24518Provides a generator of static minimal perfect hash functions. No 24519collisions occur and each item can be retrieved from the table in one 24520probe (perfect property). The hash table size corresponds to the exact 24521size of the key set and no larger (minimal property). The key set has to 24522be know in advance (static property). The hash functions are also order 24523preserving. If w2 is inserted after w1 in the generator, their 24524hashcode are in the same order. These hashing functions are very 24525convenient for use with realtime applications. 24526 24527@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 24528@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{38a}@anchor{gnat_rm/the_gnat_library id95}@anchor{38b} 24529@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) 24530 24531 24532@geindex GNAT.Random_Numbers (g-rannum.ads) 24533 24534@geindex Random number generation 24535 24536Provides random number capabilities which extend those available in the 24537standard Ada library and are more convenient to use. 24538 24539@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 24540@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{255}@anchor{gnat_rm/the_gnat_library id96}@anchor{38c} 24541@section @code{GNAT.Regexp} (@code{g-regexp.ads}) 24542 24543 24544@geindex GNAT.Regexp (g-regexp.ads) 24545 24546@geindex Regular expressions 24547 24548@geindex Pattern matching 24549 24550A simple implementation of regular expressions, using a subset of regular 24551expression syntax copied from familiar Unix style utilities. This is the 24552simplest of the three pattern matching packages provided, and is particularly 24553suitable for 'file globbing' applications. 24554 24555@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 24556@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id97}@anchor{38e} 24557@section @code{GNAT.Registry} (@code{g-regist.ads}) 24558 24559 24560@geindex GNAT.Registry (g-regist.ads) 24561 24562@geindex Windows Registry 24563 24564This is a high level binding to the Windows registry. It is possible to 24565do simple things like reading a key value, creating a new key. For full 24566registry API, but at a lower level of abstraction, refer to the Win32.Winreg 24567package provided with the Win32Ada binding 24568 24569@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 24570@anchor{gnat_rm/the_gnat_library id98}@anchor{38f}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{390} 24571@section @code{GNAT.Regpat} (@code{g-regpat.ads}) 24572 24573 24574@geindex GNAT.Regpat (g-regpat.ads) 24575 24576@geindex Regular expressions 24577 24578@geindex Pattern matching 24579 24580A complete implementation of Unix-style regular expression matching, copied 24581from the original V7 style regular expression library written in C by 24582Henry Spencer (and binary compatible with this C library). 24583 24584@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 24585@anchor{gnat_rm/the_gnat_library id99}@anchor{391}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{392} 24586@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 24587 24588 24589@geindex GNAT.Rewrite_Data (g-rewdat.ads) 24590 24591@geindex Rewrite data 24592 24593A unit to rewrite on-the-fly string occurrences in a stream of 24594data. The implementation has a very minimal memory footprint as the 24595full content to be processed is not loaded into memory all at once. This makes 24596this interface usable for large files or socket streams. 24597 24598@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 24599@anchor{gnat_rm/the_gnat_library id100}@anchor{393}@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{394} 24600@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 24601 24602 24603@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 24604 24605@geindex Secondary Stack Info 24606 24607Provide the capability to query the high water mark of the current task's 24608secondary stack. 24609 24610@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 24611@anchor{gnat_rm/the_gnat_library id101}@anchor{395}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{396} 24612@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) 24613 24614 24615@geindex GNAT.Semaphores (g-semaph.ads) 24616 24617@geindex Semaphores 24618 24619Provides classic counting and binary semaphores using protected types. 24620 24621@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 24622@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{397}@anchor{gnat_rm/the_gnat_library id102}@anchor{398} 24623@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) 24624 24625 24626@geindex GNAT.Serial_Communications (g-sercom.ads) 24627 24628@geindex Serial_Communications 24629 24630Provides a simple interface to send and receive data over a serial 24631port. This is only supported on GNU/Linux and Windows. 24632 24633@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 24634@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{399}@anchor{gnat_rm/the_gnat_library id103}@anchor{39a} 24635@section @code{GNAT.SHA1} (@code{g-sha1.ads}) 24636 24637 24638@geindex GNAT.SHA1 (g-sha1.ads) 24639 24640@geindex Secure Hash Algorithm SHA-1 24641 24642Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 24643and RFC 3174, and the HMAC-SHA1 message authentication function as described 24644in RFC 2104 and FIPS PUB 198. 24645 24646@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 24647@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{39b}@anchor{gnat_rm/the_gnat_library id104}@anchor{39c} 24648@section @code{GNAT.SHA224} (@code{g-sha224.ads}) 24649 24650 24651@geindex GNAT.SHA224 (g-sha224.ads) 24652 24653@geindex Secure Hash Algorithm SHA-224 24654 24655Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 24656and the HMAC-SHA224 message authentication function as described 24657in RFC 2104 and FIPS PUB 198. 24658 24659@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 24660@anchor{gnat_rm/the_gnat_library id105}@anchor{39d}@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{39e} 24661@section @code{GNAT.SHA256} (@code{g-sha256.ads}) 24662 24663 24664@geindex GNAT.SHA256 (g-sha256.ads) 24665 24666@geindex Secure Hash Algorithm SHA-256 24667 24668Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 24669and the HMAC-SHA256 message authentication function as described 24670in RFC 2104 and FIPS PUB 198. 24671 24672@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 24673@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{39f}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a0} 24674@section @code{GNAT.SHA384} (@code{g-sha384.ads}) 24675 24676 24677@geindex GNAT.SHA384 (g-sha384.ads) 24678 24679@geindex Secure Hash Algorithm SHA-384 24680 24681Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 24682and the HMAC-SHA384 message authentication function as described 24683in RFC 2104 and FIPS PUB 198. 24684 24685@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 24686@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a1}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a2} 24687@section @code{GNAT.SHA512} (@code{g-sha512.ads}) 24688 24689 24690@geindex GNAT.SHA512 (g-sha512.ads) 24691 24692@geindex Secure Hash Algorithm SHA-512 24693 24694Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 24695and the HMAC-SHA512 message authentication function as described 24696in RFC 2104 and FIPS PUB 198. 24697 24698@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24699@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3a3}@anchor{gnat_rm/the_gnat_library id108}@anchor{3a4} 24700@section @code{GNAT.Signals} (@code{g-signal.ads}) 24701 24702 24703@geindex GNAT.Signals (g-signal.ads) 24704 24705@geindex Signals 24706 24707Provides the ability to manipulate the blocked status of signals on supported 24708targets. 24709 24710@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24711@anchor{gnat_rm/the_gnat_library id109}@anchor{3a5}@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a6} 24712@section @code{GNAT.Sockets} (@code{g-socket.ads}) 24713 24714 24715@geindex GNAT.Sockets (g-socket.ads) 24716 24717@geindex Sockets 24718 24719A high level and portable interface to develop sockets based applications. 24720This package is based on the sockets thin binding found in 24721@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 24722on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24723the LynxOS cross port. 24724 24725@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24726@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a7}@anchor{gnat_rm/the_gnat_library id110}@anchor{3a8} 24727@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) 24728 24729 24730@geindex GNAT.Source_Info (g-souinf.ads) 24731 24732@geindex Source Information 24733 24734Provides subprograms that give access to source code information known at 24735compile time, such as the current file name and line number. Also provides 24736subprograms yielding the date and time of the current compilation (like the 24737C macros @code{__DATE__} and @code{__TIME__}) 24738 24739@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 24740@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3a9}@anchor{gnat_rm/the_gnat_library id111}@anchor{3aa} 24741@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) 24742 24743 24744@geindex GNAT.Spelling_Checker (g-speche.ads) 24745 24746@geindex Spell checking 24747 24748Provides a function for determining whether one string is a plausible 24749near misspelling of another string. 24750 24751@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 24752@anchor{gnat_rm/the_gnat_library id112}@anchor{3ab}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3ac} 24753@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 24754 24755 24756@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 24757 24758@geindex Spell checking 24759 24760Provides a generic function that can be instantiated with a string type for 24761determining whether one string is a plausible near misspelling of another 24762string. 24763 24764@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 24765@anchor{gnat_rm/the_gnat_library id113}@anchor{3ad}@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3ae} 24766@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 24767 24768 24769@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 24770 24771@geindex SPITBOL pattern matching 24772 24773@geindex Pattern matching 24774 24775A complete implementation of SNOBOL4 style pattern matching. This is the 24776most elaborate of the pattern matching packages provided. It fully duplicates 24777the SNOBOL4 dynamic pattern construction and matching capabilities, using the 24778efficient algorithm developed by Robert Dewar for the SPITBOL system. 24779 24780@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 24781@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3af}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b0} 24782@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) 24783 24784 24785@geindex GNAT.Spitbol (g-spitbo.ads) 24786 24787@geindex SPITBOL interface 24788 24789The top level package of the collection of SPITBOL-style functionality, this 24790package provides basic SNOBOL4 string manipulation functions, such as 24791Pad, Reverse, Trim, Substr capability, as well as a generic table function 24792useful for constructing arbitrary mappings from strings in the style of 24793the SNOBOL4 TABLE function. 24794 24795@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 24796@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b1}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b2} 24797@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 24798 24799 24800@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 24801 24802@geindex Sets of strings 24803 24804@geindex SPITBOL Tables 24805 24806A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24807for type @code{Standard.Boolean}, giving an implementation of sets of 24808string values. 24809 24810@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 24811@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3b3}@anchor{gnat_rm/the_gnat_library id116}@anchor{3b4} 24812@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 24813 24814 24815@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 24816 24817@geindex Integer maps 24818 24819@geindex Maps 24820 24821@geindex SPITBOL Tables 24822 24823A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24824for type @code{Standard.Integer}, giving an implementation of maps 24825from string to integer values. 24826 24827@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 24828@anchor{gnat_rm/the_gnat_library id117}@anchor{3b5}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b6} 24829@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 24830 24831 24832@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 24833 24834@geindex String maps 24835 24836@geindex Maps 24837 24838@geindex SPITBOL Tables 24839 24840A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 24841a variable length string type, giving an implementation of general 24842maps from strings to strings. 24843 24844@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 24845@anchor{gnat_rm/the_gnat_library id118}@anchor{3b7}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b8} 24846@section @code{GNAT.SSE} (@code{g-sse.ads}) 24847 24848 24849@geindex GNAT.SSE (g-sse.ads) 24850 24851Root of a set of units aimed at offering Ada bindings to a subset of 24852the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 24853targets. It exposes vector component types together with a general 24854introduction to the binding contents and use. 24855 24856@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library 24857@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3b9}@anchor{gnat_rm/the_gnat_library id119}@anchor{3ba} 24858@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 24859 24860 24861@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 24862 24863SSE vector types for use with SSE related intrinsics. 24864 24865@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 24866@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3bb}@anchor{gnat_rm/the_gnat_library id120}@anchor{3bc} 24867@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) 24868 24869 24870@geindex GNAT.String_Hash (g-strhas.ads) 24871 24872@geindex Hash functions 24873 24874Provides a generic hash function working on arrays of scalars. Both the scalar 24875type and the hash result type are parameters. 24876 24877@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library 24878@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3bd}@anchor{gnat_rm/the_gnat_library id121}@anchor{3be} 24879@section @code{GNAT.Strings} (@code{g-string.ads}) 24880 24881 24882@geindex GNAT.Strings (g-string.ads) 24883 24884Common String access types and related subprograms. Basically it 24885defines a string access and an array of string access types. 24886 24887@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 24888@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3bf}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c0} 24889@section @code{GNAT.String_Split} (@code{g-strspl.ads}) 24890 24891 24892@geindex GNAT.String_Split (g-strspl.ads) 24893 24894@geindex String splitter 24895 24896Useful string manipulation routines: given a set of separators, split 24897a string wherever the separators appear, and provide direct access 24898to the resulting slices. This package is instantiated from 24899@code{GNAT.Array_Split}. 24900 24901@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 24902@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c1}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c2} 24903@section @code{GNAT.Table} (@code{g-table.ads}) 24904 24905 24906@geindex GNAT.Table (g-table.ads) 24907 24908@geindex Table implementation 24909 24910@geindex Arrays 24911@geindex extendable 24912 24913A generic package providing a single dimension array abstraction where the 24914length of the array can be dynamically modified. 24915 24916This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 24917except that this package declares a single instance of the table type, 24918while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 24919used to define dynamic instances of the table. 24920 24921@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 24922@anchor{gnat_rm/the_gnat_library id124}@anchor{3c3}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3c4} 24923@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) 24924 24925 24926@geindex GNAT.Task_Lock (g-tasloc.ads) 24927 24928@geindex Task synchronization 24929 24930@geindex Task locking 24931 24932@geindex Locking 24933 24934A very simple facility for locking and unlocking sections of code using a 24935single global task lock. Appropriate for use in situations where contention 24936between tasks is very rarely expected. 24937 24938@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 24939@anchor{gnat_rm/the_gnat_library id125}@anchor{3c5}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c6} 24940@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) 24941 24942 24943@geindex GNAT.Time_Stamp (g-timsta.ads) 24944 24945@geindex Time stamp 24946 24947@geindex Current time 24948 24949Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 24950represents the current date and time in ISO 8601 format. This is a very simple 24951routine with minimal code and there are no dependencies on any other unit. 24952 24953@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 24954@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c7}@anchor{gnat_rm/the_gnat_library id126}@anchor{3c8} 24955@section @code{GNAT.Threads} (@code{g-thread.ads}) 24956 24957 24958@geindex GNAT.Threads (g-thread.ads) 24959 24960@geindex Foreign threads 24961 24962@geindex Threads 24963@geindex foreign 24964 24965Provides facilities for dealing with foreign threads which need to be known 24966by the GNAT run-time system. Consult the documentation of this package for 24967further details if your program has threads that are created by a non-Ada 24968environment which then accesses Ada code. 24969 24970@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 24971@anchor{gnat_rm/the_gnat_library id127}@anchor{3c9}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3ca} 24972@section @code{GNAT.Traceback} (@code{g-traceb.ads}) 24973 24974 24975@geindex GNAT.Traceback (g-traceb.ads) 24976 24977@geindex Trace back facilities 24978 24979Provides a facility for obtaining non-symbolic traceback information, useful 24980in various debugging situations. 24981 24982@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 24983@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3cb}@anchor{gnat_rm/the_gnat_library id128}@anchor{3cc} 24984@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 24985 24986 24987@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 24988 24989@geindex Trace back facilities 24990 24991@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 24992@anchor{gnat_rm/the_gnat_library id129}@anchor{3cd}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3ce} 24993@section @code{GNAT.UTF_32} (@code{g-table.ads}) 24994 24995 24996@geindex GNAT.UTF_32 (g-table.ads) 24997 24998@geindex Wide character codes 24999 25000This is a package intended to be used in conjunction with the 25001@code{Wide_Character} type in Ada 95 and the 25002@code{Wide_Wide_Character} type in Ada 2005 (available 25003in @code{GNAT} in Ada 2005 mode). This package contains 25004Unicode categorization routines, as well as lexical 25005categorization routines corresponding to the Ada 2005 25006lexical rules for identifiers and strings, and also a 25007lower case to upper case fold routine corresponding to 25008the Ada 2005 rules for identifier equivalence. 25009 25010@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 25011@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3cf}@anchor{gnat_rm/the_gnat_library id130}@anchor{3d0} 25012@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 25013 25014 25015@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 25016 25017@geindex Spell checking 25018 25019Provides a function for determining whether one wide wide string is a plausible 25020near misspelling of another wide wide string, where the strings are represented 25021using the UTF_32_String type defined in System.Wch_Cnv. 25022 25023@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 25024@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d1}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d2} 25025@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 25026 25027 25028@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 25029 25030@geindex Spell checking 25031 25032Provides a function for determining whether one wide string is a plausible 25033near misspelling of another wide string. 25034 25035@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 25036@anchor{gnat_rm/the_gnat_library id132}@anchor{3d3}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3d4} 25037@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 25038 25039 25040@geindex GNAT.Wide_String_Split (g-wistsp.ads) 25041 25042@geindex Wide_String splitter 25043 25044Useful wide string manipulation routines: given a set of separators, split 25045a wide string wherever the separators appear, and provide direct access 25046to the resulting slices. This package is instantiated from 25047@code{GNAT.Array_Split}. 25048 25049@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 25050@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d5}@anchor{gnat_rm/the_gnat_library id133}@anchor{3d6} 25051@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 25052 25053 25054@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 25055 25056@geindex Spell checking 25057 25058Provides a function for determining whether one wide wide string is a plausible 25059near misspelling of another wide wide string. 25060 25061@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 25062@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d7}@anchor{gnat_rm/the_gnat_library id134}@anchor{3d8} 25063@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 25064 25065 25066@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 25067 25068@geindex Wide_Wide_String splitter 25069 25070Useful wide wide string manipulation routines: given a set of separators, split 25071a wide wide string wherever the separators appear, and provide direct access 25072to the resulting slices. This package is instantiated from 25073@code{GNAT.Array_Split}. 25074 25075@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 25076@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d9}@anchor{gnat_rm/the_gnat_library id135}@anchor{3da} 25077@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) 25078 25079 25080@geindex Interfaces.C.Extensions (i-cexten.ads) 25081 25082This package contains additional C-related definitions, intended 25083for use with either manually or automatically generated bindings 25084to C libraries. 25085 25086@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 25087@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3db}@anchor{gnat_rm/the_gnat_library id136}@anchor{3dc} 25088@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) 25089 25090 25091@geindex Interfaces.C.Streams (i-cstrea.ads) 25092 25093@geindex C streams 25094@geindex interfacing 25095 25096This package is a binding for the most commonly used operations 25097on C streams. 25098 25099@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 25100@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3dd}@anchor{gnat_rm/the_gnat_library id137}@anchor{3de} 25101@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 25102 25103 25104@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 25105 25106@geindex IBM Packed Format 25107 25108@geindex Packed Decimal 25109 25110This package provides a set of routines for conversions to and 25111from a packed decimal format compatible with that used on IBM 25112mainframes. 25113 25114@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 25115@anchor{gnat_rm/the_gnat_library id138}@anchor{3df}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e0} 25116@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) 25117 25118 25119@geindex Interfaces.VxWorks (i-vxwork.ads) 25120 25121@geindex Interfacing to VxWorks 25122 25123@geindex VxWorks 25124@geindex interfacing 25125 25126This package provides a limited binding to the VxWorks API. 25127In particular, it interfaces with the 25128VxWorks hardware interrupt facilities. 25129 25130@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 25131@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e1}@anchor{gnat_rm/the_gnat_library id139}@anchor{3e2} 25132@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) 25133 25134 25135@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) 25136 25137@geindex Interfacing to VxWorks 25138 25139@geindex VxWorks 25140@geindex interfacing 25141 25142This package provides a way for users to replace the use of 25143intConnect() with a custom routine for installing interrupt 25144handlers. 25145 25146@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library 25147@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3e3}@anchor{gnat_rm/the_gnat_library id140}@anchor{3e4} 25148@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 25149 25150 25151@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 25152 25153@geindex Interfacing to VxWorks' I/O 25154 25155@geindex VxWorks 25156@geindex I/O interfacing 25157 25158@geindex VxWorks 25159@geindex Get_Immediate 25160 25161@geindex Get_Immediate 25162@geindex VxWorks 25163 25164This package provides a binding to the ioctl (IO/Control) 25165function of VxWorks, defining a set of option values and 25166function codes. A particular use of this package is 25167to enable the use of Get_Immediate under VxWorks. 25168 25169@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 25170@anchor{gnat_rm/the_gnat_library id141}@anchor{3e5}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e6} 25171@section @code{System.Address_Image} (@code{s-addima.ads}) 25172 25173 25174@geindex System.Address_Image (s-addima.ads) 25175 25176@geindex Address image 25177 25178@geindex Image 25179@geindex of an address 25180 25181This function provides a useful debugging 25182function that gives an (implementation dependent) 25183string which identifies an address. 25184 25185@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 25186@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e7}@anchor{gnat_rm/the_gnat_library id142}@anchor{3e8} 25187@section @code{System.Assertions} (@code{s-assert.ads}) 25188 25189 25190@geindex System.Assertions (s-assert.ads) 25191 25192@geindex Assertions 25193 25194@geindex Assert_Failure 25195@geindex exception 25196 25197This package provides the declaration of the exception raised 25198by an run-time assertion failure, as well as the routine that 25199is used internally to raise this assertion. 25200 25201@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 25202@anchor{gnat_rm/the_gnat_library id143}@anchor{3e9}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3ea} 25203@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) 25204 25205 25206@geindex System.Atomic_Counters (s-atocou.ads) 25207 25208This package provides the declaration of an atomic counter type, 25209together with efficient routines (using hardware 25210synchronization primitives) for incrementing, decrementing, 25211and testing of these counters. This package is implemented 25212on most targets, including all Alpha, ia64, PowerPC, SPARC V9, 25213x86, and x86_64 platforms. 25214 25215@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 25216@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3eb}@anchor{gnat_rm/the_gnat_library id144}@anchor{3ec} 25217@section @code{System.Memory} (@code{s-memory.ads}) 25218 25219 25220@geindex System.Memory (s-memory.ads) 25221 25222@geindex Memory allocation 25223 25224This package provides the interface to the low level routines used 25225by the generated code for allocation and freeing storage for the 25226default storage pool (analogous to the C routines malloc and free. 25227It also provides a reallocation interface analogous to the C routine 25228realloc. The body of this unit may be modified to provide alternative 25229allocation mechanisms for the default pool, and in addition, direct 25230calls to this unit may be made for low level allocation uses (for 25231example see the body of @code{GNAT.Tables}). 25232 25233@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 25234@anchor{gnat_rm/the_gnat_library id145}@anchor{3ed}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3ee} 25235@section @code{System.Multiprocessors} (@code{s-multip.ads}) 25236 25237 25238@geindex System.Multiprocessors (s-multip.ads) 25239 25240@geindex Multiprocessor interface 25241 25242This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25243in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25244technically an implementation-defined addition). 25245 25246@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 25247@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3ef}@anchor{gnat_rm/the_gnat_library id146}@anchor{3f0} 25248@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 25249 25250 25251@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 25252 25253@geindex Multiprocessor interface 25254 25255This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25256in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25257technically an implementation-defined addition). 25258 25259@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 25260@anchor{gnat_rm/the_gnat_library id147}@anchor{3f1}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f2} 25261@section @code{System.Partition_Interface} (@code{s-parint.ads}) 25262 25263 25264@geindex System.Partition_Interface (s-parint.ads) 25265 25266@geindex Partition interfacing functions 25267 25268This package provides facilities for partition interfacing. It 25269is used primarily in a distribution context when using Annex E 25270with @code{GLADE}. 25271 25272@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 25273@anchor{gnat_rm/the_gnat_library id148}@anchor{3f3}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3f4} 25274@section @code{System.Pool_Global} (@code{s-pooglo.ads}) 25275 25276 25277@geindex System.Pool_Global (s-pooglo.ads) 25278 25279@geindex Storage pool 25280@geindex global 25281 25282@geindex Global storage pool 25283 25284This package provides a storage pool that is equivalent to the default 25285storage pool used for access types for which no pool is specifically 25286declared. It uses malloc/free to allocate/free and does not attempt to 25287do any automatic reclamation. 25288 25289@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 25290@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f5}@anchor{gnat_rm/the_gnat_library id149}@anchor{3f6} 25291@section @code{System.Pool_Local} (@code{s-pooloc.ads}) 25292 25293 25294@geindex System.Pool_Local (s-pooloc.ads) 25295 25296@geindex Storage pool 25297@geindex local 25298 25299@geindex Local storage pool 25300 25301This package provides a storage pool that is intended for use with locally 25302defined access types. It uses malloc/free for allocate/free, and maintains 25303a list of allocated blocks, so that all storage allocated for the pool can 25304be freed automatically when the pool is finalized. 25305 25306@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 25307@anchor{gnat_rm/the_gnat_library id150}@anchor{3f7}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f8} 25308@section @code{System.Restrictions} (@code{s-restri.ads}) 25309 25310 25311@geindex System.Restrictions (s-restri.ads) 25312 25313@geindex Run-time restrictions access 25314 25315This package provides facilities for accessing at run time 25316the status of restrictions specified at compile time for 25317the partition. Information is available both with regard 25318to actual restrictions specified, and with regard to 25319compiler determined information on which restrictions 25320are violated by one or more packages in the partition. 25321 25322@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 25323@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f9}@anchor{gnat_rm/the_gnat_library id151}@anchor{3fa} 25324@section @code{System.Rident} (@code{s-rident.ads}) 25325 25326 25327@geindex System.Rident (s-rident.ads) 25328 25329@geindex Restrictions definitions 25330 25331This package provides definitions of the restrictions 25332identifiers supported by GNAT, and also the format of 25333the restrictions provided in package System.Restrictions. 25334It is not normally necessary to @code{with} this generic package 25335since the necessary instantiation is included in 25336package System.Restrictions. 25337 25338@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 25339@anchor{gnat_rm/the_gnat_library id152}@anchor{3fb}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3fc} 25340@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 25341 25342 25343@geindex System.Strings.Stream_Ops (s-ststop.ads) 25344 25345@geindex Stream operations 25346 25347@geindex String stream operations 25348 25349This package provides a set of stream subprograms for standard string types. 25350It is intended primarily to support implicit use of such subprograms when 25351stream attributes are applied to string types, but the subprograms in this 25352package can be used directly by application programs. 25353 25354@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 25355@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3fd}@anchor{gnat_rm/the_gnat_library id153}@anchor{3fe} 25356@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) 25357 25358 25359@geindex System.Unsigned_Types (s-unstyp.ads) 25360 25361This package contains definitions of standard unsigned types that 25362correspond in size to the standard signed types declared in Standard, 25363and (unlike the types in Interfaces) have corresponding names. It 25364also contains some related definitions for other specialized types 25365used by the compiler in connection with packed array types. 25366 25367@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 25368@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3ff}@anchor{gnat_rm/the_gnat_library id154}@anchor{400} 25369@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) 25370 25371 25372@geindex System.Wch_Cnv (s-wchcnv.ads) 25373 25374@geindex Wide Character 25375@geindex Representation 25376 25377@geindex Wide String 25378@geindex Conversion 25379 25380@geindex Representation of wide characters 25381 25382This package provides routines for converting between 25383wide and wide wide characters and a representation as a value of type 25384@code{Standard.String}, using a specified wide character 25385encoding method. It uses definitions in 25386package @code{System.Wch_Con}. 25387 25388@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 25389@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{401}@anchor{gnat_rm/the_gnat_library id155}@anchor{402} 25390@section @code{System.Wch_Con} (@code{s-wchcon.ads}) 25391 25392 25393@geindex System.Wch_Con (s-wchcon.ads) 25394 25395This package provides definitions and descriptions of 25396the various methods used for encoding wide characters 25397in ordinary strings. These definitions are used by 25398the package @code{System.Wch_Cnv}. 25399 25400@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 25401@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{403}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{404} 25402@chapter Interfacing to Other Languages 25403 25404 25405The facilities in Annex B of the Ada Reference Manual are fully 25406implemented in GNAT, and in addition, a full interface to C++ is 25407provided. 25408 25409@menu 25410* Interfacing to C:: 25411* Interfacing to C++:: 25412* Interfacing to COBOL:: 25413* Interfacing to Fortran:: 25414* Interfacing to non-GNAT Ada code:: 25415 25416@end menu 25417 25418@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 25419@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{405}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{406} 25420@section Interfacing to C 25421 25422 25423Interfacing to C with GNAT can use one of two approaches: 25424 25425 25426@itemize * 25427 25428@item 25429The types in the package @code{Interfaces.C} may be used. 25430 25431@item 25432Standard Ada types may be used directly. This may be less portable to 25433other compilers, but will work on all GNAT compilers, which guarantee 25434correspondence between the C and Ada types. 25435@end itemize 25436 25437Pragma @code{Convention C} may be applied to Ada types, but mostly has no 25438effect, since this is the default. The following table shows the 25439correspondence between Ada scalar types and the corresponding C types. 25440 25441 25442@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 25443@headitem 25444 25445Ada Type 25446 25447@tab 25448 25449C Type 25450 25451@item 25452 25453@code{Integer} 25454 25455@tab 25456 25457@code{int} 25458 25459@item 25460 25461@code{Short_Integer} 25462 25463@tab 25464 25465@code{short} 25466 25467@item 25468 25469@code{Short_Short_Integer} 25470 25471@tab 25472 25473@code{signed char} 25474 25475@item 25476 25477@code{Long_Integer} 25478 25479@tab 25480 25481@code{long} 25482 25483@item 25484 25485@code{Long_Long_Integer} 25486 25487@tab 25488 25489@code{long long} 25490 25491@item 25492 25493@code{Short_Float} 25494 25495@tab 25496 25497@code{float} 25498 25499@item 25500 25501@code{Float} 25502 25503@tab 25504 25505@code{float} 25506 25507@item 25508 25509@code{Long_Float} 25510 25511@tab 25512 25513@code{double} 25514 25515@item 25516 25517@code{Long_Long_Float} 25518 25519@tab 25520 25521This is the longest floating-point type supported by the hardware. 25522 25523@end multitable 25524 25525 25526Additionally, there are the following general correspondences between Ada 25527and C types: 25528 25529 25530@itemize * 25531 25532@item 25533Ada enumeration types map to C enumeration types directly if pragma 25534@code{Convention C} is specified, which causes them to have int 25535length. Without pragma @code{Convention C}, Ada enumeration types map to 255368, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, 25537@code{int}, respectively) depending on the number of values passed. 25538This is the only case in which pragma @code{Convention C} affects the 25539representation of an Ada type. 25540 25541@item 25542Ada access types map to C pointers, except for the case of pointers to 25543unconstrained types in Ada, which have no direct C equivalent. 25544 25545@item 25546Ada arrays map directly to C arrays. 25547 25548@item 25549Ada records map directly to C structures. 25550 25551@item 25552Packed Ada records map to C structures where all members are bit fields 25553of the length corresponding to the @code{type'Size} value in Ada. 25554@end itemize 25555 25556@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 25557@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{407}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{49} 25558@section Interfacing to C++ 25559 25560 25561The interface to C++ makes use of the following pragmas, which are 25562primarily intended to be constructed automatically using a binding generator 25563tool, although it is possible to construct them by hand. 25564 25565Using these pragmas it is possible to achieve complete 25566inter-operability between Ada tagged types and C++ class definitions. 25567See @ref{7,,Implementation Defined Pragmas}, for more details. 25568 25569 25570@table @asis 25571 25572@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} 25573 25574The argument denotes an entity in the current declarative region that is 25575declared as a tagged or untagged record type. It indicates that the type 25576corresponds to an externally declared C++ class type, and is to be laid 25577out the same way that C++ would lay out the type. 25578 25579Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 25580for backward compatibility but its functionality is available 25581using pragma @code{Import} with @code{Convention} = @code{CPP}. 25582 25583@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} 25584 25585This pragma identifies an imported function (imported in the usual way 25586with pragma @code{Import}) as corresponding to a C++ constructor. 25587@end table 25588 25589A few restrictions are placed on the use of the @code{Access} attribute 25590in conjunction with subprograms subject to convention @code{CPP}: the 25591attribute may be used neither on primitive operations of a tagged 25592record type with convention @code{CPP}, imported or not, nor on 25593subprograms imported with pragma @code{CPP_Constructor}. 25594 25595In addition, C++ exceptions are propagated and can be handled in an 25596@code{others} choice of an exception handler. The corresponding Ada 25597occurrence has no message, and the simple name of the exception identity 25598contains @code{Foreign_Exception}. Finalization and awaiting dependent 25599tasks works properly when such foreign exceptions are propagated. 25600 25601It is also possible to import a C++ exception using the following syntax: 25602 25603@example 25604LOCAL_NAME : exception; 25605pragma Import (Cpp, 25606 [Entity =>] LOCAL_NAME, 25607 [External_Name =>] static_string_EXPRESSION); 25608@end example 25609 25610The @code{External_Name} is the name of the C++ RTTI symbol. You can then 25611cover a specific C++ exception in an exception handler. 25612 25613@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 25614@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{408}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{409} 25615@section Interfacing to COBOL 25616 25617 25618Interfacing to COBOL is achieved as described in section B.4 of 25619the Ada Reference Manual. 25620 25621@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 25622@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{40a}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{40b} 25623@section Interfacing to Fortran 25624 25625 25626Interfacing to Fortran is achieved as described in section B.5 of the 25627Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 25628multi-dimensional array causes the array to be stored in column-major 25629order as required for convenient interface to Fortran. 25630 25631@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 25632@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{40c}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{40d} 25633@section Interfacing to non-GNAT Ada code 25634 25635 25636It is possible to specify the convention @code{Ada} in a pragma 25637@code{Import} or pragma @code{Export}. However this refers to 25638the calling conventions used by GNAT, which may or may not be 25639similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 25640compiler to allow interoperation. 25641 25642If arguments types are kept simple, and if the foreign compiler generally 25643follows system calling conventions, then it may be possible to integrate 25644files compiled by other Ada compilers, provided that the elaboration 25645issues are adequately addressed (for example by eliminating the 25646need for any load time elaboration). 25647 25648In particular, GNAT running on VMS is designed to 25649be highly compatible with the DEC Ada 83 compiler, so this is one 25650case in which it is possible to import foreign units of this type, 25651provided that the data items passed are restricted to simple scalar 25652values or simple record types without variants, or simple array 25653types with fixed bounds. 25654 25655@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 25656@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{40e}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{40f} 25657@chapter Specialized Needs Annexes 25658 25659 25660Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 25661required in all implementations. However, as described in this chapter, 25662GNAT implements all of these annexes: 25663 25664 25665@table @asis 25666 25667@item @emph{Systems Programming (Annex C)} 25668 25669The Systems Programming Annex is fully implemented. 25670 25671@item @emph{Real-Time Systems (Annex D)} 25672 25673The Real-Time Systems Annex is fully implemented. 25674 25675@item @emph{Distributed Systems (Annex E)} 25676 25677Stub generation is fully implemented in the GNAT compiler. In addition, 25678a complete compatible PCS is available as part of the GLADE system, 25679a separate product. When the two 25680products are used in conjunction, this annex is fully implemented. 25681 25682@item @emph{Information Systems (Annex F)} 25683 25684The Information Systems annex is fully implemented. 25685 25686@item @emph{Numerics (Annex G)} 25687 25688The Numerics Annex is fully implemented. 25689 25690@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 25691 25692The Safety and Security Annex (termed the High-Integrity Systems Annex 25693in Ada 2005) is fully implemented. 25694@end table 25695 25696@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 25697@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{410}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{411} 25698@chapter Implementation of Specific Ada Features 25699 25700 25701This chapter describes the GNAT implementation of several Ada language 25702facilities. 25703 25704@menu 25705* Machine Code Insertions:: 25706* GNAT Implementation of Tasking:: 25707* GNAT Implementation of Shared Passive Packages:: 25708* Code Generation for Array Aggregates:: 25709* The Size of Discriminated Records with Default Discriminants:: 25710* Strict Conformance to the Ada Reference Manual:: 25711 25712@end menu 25713 25714@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 25715@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{168}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{412} 25716@section Machine Code Insertions 25717 25718 25719@geindex Machine Code insertions 25720 25721Package @code{Machine_Code} provides machine code support as described 25722in the Ada Reference Manual in two separate forms: 25723 25724 25725@itemize * 25726 25727@item 25728Machine code statements, consisting of qualified expressions that 25729fit the requirements of RM section 13.8. 25730 25731@item 25732An intrinsic callable procedure, providing an alternative mechanism of 25733including machine instructions in a subprogram. 25734@end itemize 25735 25736The two features are similar, and both are closely related to the mechanism 25737provided by the asm instruction in the GNU C compiler. Full understanding 25738and use of the facilities in this package requires understanding the asm 25739instruction, see the section on Extended Asm in 25740@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 25741 25742Calls to the function @code{Asm} and the procedure @code{Asm} have identical 25743semantic restrictions and effects as described below. Both are provided so 25744that the procedure call can be used as a statement, and the function call 25745can be used to form a code_statement. 25746 25747Consider this C @code{asm} instruction: 25748 25749@example 25750asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 25751@end example 25752 25753The equivalent can be written for GNAT as: 25754 25755@example 25756Asm ("fsinx %1 %0", 25757 My_Float'Asm_Output ("=f", result), 25758 My_Float'Asm_Input ("f", angle)); 25759@end example 25760 25761The first argument to @code{Asm} is the assembler template, and is 25762identical to what is used in GNU C. This string must be a static 25763expression. The second argument is the output operand list. It is 25764either a single @code{Asm_Output} attribute reference, or a list of such 25765references enclosed in parentheses (technically an array aggregate of 25766such references). 25767 25768The @code{Asm_Output} attribute denotes a function that takes two 25769parameters. The first is a string, the second is the name of a variable 25770of the type designated by the attribute prefix. The first (string) 25771argument is required to be a static expression and designates the 25772constraint (see the section on Constraints in 25773@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 25774for the parameter; e.g., what kind of register is required. The second 25775argument is the variable to be written or updated with the 25776result. The possible values for constraint are the same as those used in 25777the RTL, and are dependent on the configuration file used to build the 25778GCC back end. If there are no output operands, then this argument may 25779either be omitted, or explicitly given as @code{No_Output_Operands}. 25780No support is provided for GNU C's symbolic names for output parameters. 25781 25782The second argument of @code{my_float'Asm_Output} functions as 25783though it were an @code{out} parameter, which is a little curious, but 25784all names have the form of expressions, so there is no syntactic 25785irregularity, even though normally functions would not be permitted 25786@code{out} parameters. The third argument is the list of input 25787operands. It is either a single @code{Asm_Input} attribute reference, or 25788a list of such references enclosed in parentheses (technically an array 25789aggregate of such references). 25790 25791The @code{Asm_Input} attribute denotes a function that takes two 25792parameters. The first is a string, the second is an expression of the 25793type designated by the prefix. The first (string) argument is required 25794to be a static expression, and is the constraint for the parameter, 25795(e.g., what kind of register is required). The second argument is the 25796value to be used as the input argument. The possible values for the 25797constraint are the same as those used in the RTL, and are dependent on 25798the configuration file used to built the GCC back end. 25799No support is provided for GNU C's symbolic names for input parameters. 25800 25801If there are no input operands, this argument may either be omitted, or 25802explicitly given as @code{No_Input_Operands}. The fourth argument, not 25803present in the above example, is a list of register names, called the 25804@emph{clobber} argument. This argument, if given, must be a static string 25805expression, and is a space or comma separated list of names of registers 25806that must be considered destroyed as a result of the @code{Asm} call. If 25807this argument is the null string (the default value), then the code 25808generator assumes that no additional registers are destroyed. 25809In addition to registers, the special clobbers @code{memory} and 25810@code{cc} as described in the GNU C docs are both supported. 25811 25812The fifth argument, not present in the above example, called the 25813@emph{volatile} argument, is by default @code{False}. It can be set to 25814the literal value @code{True} to indicate to the code generator that all 25815optimizations with respect to the instruction specified should be 25816suppressed, and in particular an instruction that has outputs 25817will still be generated, even if none of the outputs are 25818used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 25819for the full description. 25820Generally it is strongly advisable to use Volatile for any ASM statement 25821that is missing either input or output operands or to avoid unwanted 25822optimizations. A warning is generated if this advice is not followed. 25823 25824No support is provided for GNU C's @code{asm goto} feature. 25825 25826The @code{Asm} subprograms may be used in two ways. First the procedure 25827forms can be used anywhere a procedure call would be valid, and 25828correspond to what the RM calls 'intrinsic' routines. Such calls can 25829be used to intersperse machine instructions with other Ada statements. 25830Second, the function forms, which return a dummy value of the limited 25831private type @code{Asm_Insn}, can be used in code statements, and indeed 25832this is the only context where such calls are allowed. Code statements 25833appear as aggregates of the form: 25834 25835@example 25836Asm_Insn'(Asm (...)); 25837Asm_Insn'(Asm_Volatile (...)); 25838@end example 25839 25840In accordance with RM rules, such code statements are allowed only 25841within subprograms whose entire body consists of such statements. It is 25842not permissible to intermix such statements with other Ada statements. 25843 25844Typically the form using intrinsic procedure calls is more convenient 25845and more flexible. The code statement form is provided to meet the RM 25846suggestion that such a facility should be made available. The following 25847is the exact syntax of the call to @code{Asm}. As usual, if named notation 25848is used, the arguments may be given in arbitrary order, following the 25849normal rules for use of positional and named arguments: 25850 25851@example 25852ASM_CALL ::= Asm ( 25853 [Template =>] static_string_EXPRESSION 25854 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 25855 [,[Inputs =>] INPUT_OPERAND_LIST ] 25856 [,[Clobber =>] static_string_EXPRESSION ] 25857 [,[Volatile =>] static_boolean_EXPRESSION] ) 25858 25859OUTPUT_OPERAND_LIST ::= 25860 [PREFIX.]No_Output_Operands 25861| OUTPUT_OPERAND_ATTRIBUTE 25862| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 25863 25864OUTPUT_OPERAND_ATTRIBUTE ::= 25865 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 25866 25867INPUT_OPERAND_LIST ::= 25868 [PREFIX.]No_Input_Operands 25869| INPUT_OPERAND_ATTRIBUTE 25870| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 25871 25872INPUT_OPERAND_ATTRIBUTE ::= 25873 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 25874@end example 25875 25876The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 25877are declared in the package @code{Machine_Code} and must be referenced 25878according to normal visibility rules. In particular if there is no 25879@code{use} clause for this package, then appropriate package name 25880qualification is required. 25881 25882@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 25883@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{413}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{414} 25884@section GNAT Implementation of Tasking 25885 25886 25887This chapter outlines the basic GNAT approach to tasking (in particular, 25888a multi-layered library for portability) and discusses issues related 25889to compliance with the Real-Time Systems Annex. 25890 25891@menu 25892* Mapping Ada Tasks onto the Underlying Kernel Threads:: 25893* Ensuring Compliance with the Real-Time Annex:: 25894* Support for Locking Policies:: 25895 25896@end menu 25897 25898@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 25899@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{416} 25900@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 25901 25902 25903GNAT's run-time support comprises two layers: 25904 25905 25906@itemize * 25907 25908@item 25909GNARL (GNAT Run-time Layer) 25910 25911@item 25912GNULL (GNAT Low-level Library) 25913@end itemize 25914 25915In GNAT, Ada's tasking services rely on a platform and OS independent 25916layer known as GNARL. This code is responsible for implementing the 25917correct semantics of Ada's task creation, rendezvous, protected 25918operations etc. 25919 25920GNARL decomposes Ada's tasking semantics into simpler lower level 25921operations such as create a thread, set the priority of a thread, 25922yield, create a lock, lock/unlock, etc. The spec for these low-level 25923operations constitutes GNULLI, the GNULL Interface. This interface is 25924directly inspired from the POSIX real-time API. 25925 25926If the underlying executive or OS implements the POSIX standard 25927faithfully, the GNULL Interface maps as is to the services offered by 25928the underlying kernel. Otherwise, some target dependent glue code maps 25929the services offered by the underlying kernel to the semantics expected 25930by GNARL. 25931 25932Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 25933key point is that each Ada task is mapped on a thread in the underlying 25934kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 25935 25936In addition Ada task priorities map onto the underlying thread priorities. 25937Mapping Ada tasks onto the underlying kernel threads has several advantages: 25938 25939 25940@itemize * 25941 25942@item 25943The underlying scheduler is used to schedule the Ada tasks. This 25944makes Ada tasks as efficient as kernel threads from a scheduling 25945standpoint. 25946 25947@item 25948Interaction with code written in C containing threads is eased 25949since at the lowest level Ada tasks and C threads map onto the same 25950underlying kernel concept. 25951 25952@item 25953When an Ada task is blocked during I/O the remaining Ada tasks are 25954able to proceed. 25955 25956@item 25957On multiprocessor systems Ada tasks can execute in parallel. 25958@end itemize 25959 25960Some threads libraries offer a mechanism to fork a new process, with the 25961child process duplicating the threads from the parent. 25962GNAT does not 25963support this functionality when the parent contains more than one task. 25964 25965@geindex Forking a new process 25966 25967@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 25968@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{418} 25969@subsection Ensuring Compliance with the Real-Time Annex 25970 25971 25972@geindex Real-Time Systems Annex compliance 25973 25974Although mapping Ada tasks onto 25975the underlying threads has significant advantages, it does create some 25976complications when it comes to respecting the scheduling semantics 25977specified in the real-time annex (Annex D). 25978 25979For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 25980scheduling policy states: 25981 25982@quotation 25983 25984@emph{When the active priority of a ready task that is not running 25985changes, or the setting of its base priority takes effect, the 25986task is removed from the ready queue for its old active priority 25987and is added at the tail of the ready queue for its new active 25988priority, except in the case where the active priority is lowered 25989due to the loss of inherited priority, in which case the task is 25990added at the head of the ready queue for its new active priority.} 25991@end quotation 25992 25993While most kernels do put tasks at the end of the priority queue when 25994a task changes its priority, (which respects the main 25995FIFO_Within_Priorities requirement), almost none keep a thread at the 25996beginning of its priority queue when its priority drops from the loss 25997of inherited priority. 25998 25999As a result most vendors have provided incomplete Annex D implementations. 26000 26001The GNAT run-time, has a nice cooperative solution to this problem 26002which ensures that accurate FIFO_Within_Priorities semantics are 26003respected. 26004 26005The principle is as follows. When an Ada task T is about to start 26006running, it checks whether some other Ada task R with the same 26007priority as T has been suspended due to the loss of priority 26008inheritance. If this is the case, T yields and is placed at the end of 26009its priority queue. When R arrives at the front of the queue it 26010executes. 26011 26012Note that this simple scheme preserves the relative order of the tasks 26013that were ready to execute in the priority queue where R has been 26014placed at the end. 26015 26016@c Support_for_Locking_Policies 26017 26018@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking 26019@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{419} 26020@subsection Support for Locking Policies 26021 26022 26023This section specifies which policies specified by pragma Locking_Policy 26024are supported on which platforms. 26025 26026GNAT supports the standard @code{Ceiling_Locking} policy, and the 26027implementation defined @code{Inheritance_Locking} and 26028@code{Concurrent_Readers_Locking} policies. 26029 26030@code{Ceiling_Locking} is supported on all platforms if the operating system 26031supports it. In particular, @code{Ceiling_Locking} is not supported on 26032VxWorks. 26033@code{Inheritance_Locking} is supported on 26034Linux, 26035Darwin (Mac OS X), 26036LynxOS 178, 26037and VxWorks. 26038@code{Concurrent_Readers_Locking} is supported on Linux. 26039 26040Notes about @code{Ceiling_Locking} on Linux: 26041If the process is running as 'root', ceiling locking is used. 26042If the capabilities facility is installed 26043("sudo apt-get --assume-yes install libcap-dev" on Ubuntu, 26044for example), 26045and the program is linked against that library 26046("-largs -lcap"), 26047and the executable file has the cap_sys_nice capability 26048("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"), 26049then ceiling locking is used. 26050Otherwise, the @code{Ceiling_Locking} policy is ignored. 26051 26052@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 26053@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{41a}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{41b} 26054@section GNAT Implementation of Shared Passive Packages 26055 26056 26057@geindex Shared passive packages 26058 26059GNAT fully implements the 26060@geindex pragma Shared_Passive 26061pragma 26062@code{Shared_Passive} for 26063the purpose of designating shared passive packages. 26064This allows the use of passive partitions in the 26065context described in the Ada Reference Manual; i.e., for communication 26066between separate partitions of a distributed application using the 26067features in Annex E. 26068 26069@geindex Annex E 26070 26071@geindex Distribution Systems Annex 26072 26073However, the implementation approach used by GNAT provides for more 26074extensive usage as follows: 26075 26076 26077@table @asis 26078 26079@item @emph{Communication between separate programs} 26080 26081This allows separate programs to access the data in passive 26082partitions, using protected objects for synchronization where 26083needed. The only requirement is that the two programs have a 26084common shared file system. It is even possible for programs 26085running on different machines with different architectures 26086(e.g., different endianness) to communicate via the data in 26087a passive partition. 26088 26089@item @emph{Persistence between program runs} 26090 26091The data in a passive package can persist from one run of a 26092program to another, so that a later program sees the final 26093values stored by a previous run of the same program. 26094@end table 26095 26096The implementation approach used is to store the data in files. A 26097separate stream file is created for each object in the package, and 26098an access to an object causes the corresponding file to be read or 26099written. 26100 26101@geindex SHARED_MEMORY_DIRECTORY environment variable 26102 26103The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 26104set to the directory to be used for these files. 26105The files in this directory 26106have names that correspond to their fully qualified names. For 26107example, if we have the package 26108 26109@example 26110package X is 26111 pragma Shared_Passive (X); 26112 Y : Integer; 26113 Z : Float; 26114end X; 26115@end example 26116 26117and the environment variable is set to @code{/stemp/}, then the files created 26118will have the names: 26119 26120@example 26121/stemp/x.y 26122/stemp/x.z 26123@end example 26124 26125These files are created when a value is initially written to the object, and 26126the files are retained until manually deleted. This provides the persistence 26127semantics. If no file exists, it means that no partition has assigned a value 26128to the variable; in this case the initial value declared in the package 26129will be used. This model ensures that there are no issues in synchronizing 26130the elaboration process, since elaboration of passive packages elaborates the 26131initial values, but does not create the files. 26132 26133The files are written using normal @code{Stream_IO} access. 26134If you want to be able 26135to communicate between programs or partitions running on different 26136architectures, then you should use the XDR versions of the stream attribute 26137routines, since these are architecture independent. 26138 26139If active synchronization is required for access to the variables in the 26140shared passive package, then as described in the Ada Reference Manual, the 26141package may contain protected objects used for this purpose. In this case 26142a lock file (whose name is @code{___lock} (three underscores) 26143is created in the shared memory directory. 26144 26145@geindex ___lock file (for shared passive packages) 26146 26147This is used to provide the required locking 26148semantics for proper protected object synchronization. 26149 26150GNAT supports shared passive packages on all platforms 26151except for OpenVMS. 26152 26153@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 26154@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{41d} 26155@section Code Generation for Array Aggregates 26156 26157 26158Aggregates have a rich syntax and allow the user to specify the values of 26159complex data structures by means of a single construct. As a result, the 26160code generated for aggregates can be quite complex and involve loops, case 26161statements and multiple assignments. In the simplest cases, however, the 26162compiler will recognize aggregates whose components and constraints are 26163fully static, and in those cases the compiler will generate little or no 26164executable code. The following is an outline of the code that GNAT generates 26165for various aggregate constructs. For further details, you will find it 26166useful to examine the output produced by the -gnatG flag to see the expanded 26167source that is input to the code generator. You may also want to examine 26168the assembly code generated at various levels of optimization. 26169 26170The code generated for aggregates depends on the context, the component values, 26171and the type. In the context of an object declaration the code generated is 26172generally simpler than in the case of an assignment. As a general rule, static 26173component values and static subtypes also lead to simpler code. 26174 26175@menu 26176* Static constant aggregates with static bounds:: 26177* Constant aggregates with unconstrained nominal types:: 26178* Aggregates with static bounds:: 26179* Aggregates with nonstatic bounds:: 26180* Aggregates in assignment statements:: 26181 26182@end menu 26183 26184@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 26185@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{41f} 26186@subsection Static constant aggregates with static bounds 26187 26188 26189For the declarations: 26190 26191@example 26192type One_Dim is array (1..10) of integer; 26193ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 26194@end example 26195 26196GNAT generates no executable code: the constant ar0 is placed in static memory. 26197The same is true for constant aggregates with named associations: 26198 26199@example 26200Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 26201Cr3 : constant One_Dim := (others => 7777); 26202@end example 26203 26204The same is true for multidimensional constant arrays such as: 26205 26206@example 26207type two_dim is array (1..3, 1..3) of integer; 26208Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 26209@end example 26210 26211The same is true for arrays of one-dimensional arrays: the following are 26212static: 26213 26214@example 26215type ar1b is array (1..3) of boolean; 26216type ar_ar is array (1..3) of ar1b; 26217None : constant ar1b := (others => false); -- fully static 26218None2 : constant ar_ar := (1..3 => None); -- fully static 26219@end example 26220 26221However, for multidimensional aggregates with named associations, GNAT will 26222generate assignments and loops, even if all associations are static. The 26223following two declarations generate a loop for the first dimension, and 26224individual component assignments for the second dimension: 26225 26226@example 26227Zero1: constant two_dim := (1..3 => (1..3 => 0)); 26228Zero2: constant two_dim := (others => (others => 0)); 26229@end example 26230 26231@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 26232@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{421} 26233@subsection Constant aggregates with unconstrained nominal types 26234 26235 26236In such cases the aggregate itself establishes the subtype, so that 26237associations with @code{others} cannot be used. GNAT determines the 26238bounds for the actual subtype of the aggregate, and allocates the 26239aggregate statically as well. No code is generated for the following: 26240 26241@example 26242type One_Unc is array (natural range <>) of integer; 26243Cr_Unc : constant One_Unc := (12,24,36); 26244@end example 26245 26246@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 26247@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{423} 26248@subsection Aggregates with static bounds 26249 26250 26251In all previous examples the aggregate was the initial (and immutable) value 26252of a constant. If the aggregate initializes a variable, then code is generated 26253for it as a combination of individual assignments and loops over the target 26254object. The declarations 26255 26256@example 26257Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 26258Cr_Var2 : One_Dim := (others > -1); 26259@end example 26260 26261generate the equivalent of 26262 26263@example 26264Cr_Var1 (1) := 2; 26265Cr_Var1 (2) := 3; 26266Cr_Var1 (3) := 5; 26267Cr_Var1 (4) := 11; 26268 26269for I in Cr_Var2'range loop 26270 Cr_Var2 (I) := -1; 26271end loop; 26272@end example 26273 26274@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 26275@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{424}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{425} 26276@subsection Aggregates with nonstatic bounds 26277 26278 26279If the bounds of the aggregate are not statically compatible with the bounds 26280of the nominal subtype of the target, then constraint checks have to be 26281generated on the bounds. For a multidimensional array, constraint checks may 26282have to be applied to sub-arrays individually, if they do not have statically 26283compatible subtypes. 26284 26285@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 26286@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{426}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{427} 26287@subsection Aggregates in assignment statements 26288 26289 26290In general, aggregate assignment requires the construction of a temporary, 26291and a copy from the temporary to the target of the assignment. This is because 26292it is not always possible to convert the assignment into a series of individual 26293component assignments. For example, consider the simple case: 26294 26295@example 26296A := (A(2), A(1)); 26297@end example 26298 26299This cannot be converted into: 26300 26301@example 26302A(1) := A(2); 26303A(2) := A(1); 26304@end example 26305 26306So the aggregate has to be built first in a separate location, and then 26307copied into the target. GNAT recognizes simple cases where this intermediate 26308step is not required, and the assignments can be performed in place, directly 26309into the target. The following sufficient criteria are applied: 26310 26311 26312@itemize * 26313 26314@item 26315The bounds of the aggregate are static, and the associations are static. 26316 26317@item 26318The components of the aggregate are static constants, names of 26319simple variables that are not renamings, or expressions not involving 26320indexed components whose operands obey these rules. 26321@end itemize 26322 26323If any of these conditions are violated, the aggregate will be built in 26324a temporary (created either by the front-end or the code generator) and then 26325that temporary will be copied onto the target. 26326 26327@node The Size of Discriminated Records with Default Discriminants,Strict Conformance to the Ada Reference Manual,Code Generation for Array Aggregates,Implementation of Specific Ada Features 26328@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{428}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{429} 26329@section The Size of Discriminated Records with Default Discriminants 26330 26331 26332If a discriminated type @code{T} has discriminants with default values, it is 26333possible to declare an object of this type without providing an explicit 26334constraint: 26335 26336@example 26337type Size is range 1..100; 26338 26339type Rec (D : Size := 15) is record 26340 Name : String (1..D); 26341end T; 26342 26343Word : Rec; 26344@end example 26345 26346Such an object is said to be @emph{unconstrained}. 26347The discriminant of the object 26348can be modified by a full assignment to the object, as long as it preserves the 26349relation between the value of the discriminant, and the value of the components 26350that depend on it: 26351 26352@example 26353Word := (3, "yes"); 26354 26355Word := (5, "maybe"); 26356 26357Word := (5, "no"); -- raises Constraint_Error 26358@end example 26359 26360In order to support this behavior efficiently, an unconstrained object is 26361given the maximum size that any value of the type requires. In the case 26362above, @code{Word} has storage for the discriminant and for 26363a @code{String} of length 100. 26364It is important to note that unconstrained objects do not require dynamic 26365allocation. It would be an improper implementation to place on the heap those 26366components whose size depends on discriminants. (This improper implementation 26367was used by some Ada83 compilers, where the @code{Name} component above 26368would have 26369been stored as a pointer to a dynamic string). Following the principle that 26370dynamic storage management should never be introduced implicitly, 26371an Ada compiler should reserve the full size for an unconstrained declared 26372object, and place it on the stack. 26373 26374This maximum size approach 26375has been a source of surprise to some users, who expect the default 26376values of the discriminants to determine the size reserved for an 26377unconstrained object: "If the default is 15, why should the object occupy 26378a larger size?" 26379The answer, of course, is that the discriminant may be later modified, 26380and its full range of values must be taken into account. This is why the 26381declaration: 26382 26383@example 26384type Rec (D : Positive := 15) is record 26385 Name : String (1..D); 26386end record; 26387 26388Too_Large : Rec; 26389@end example 26390 26391is flagged by the compiler with a warning: 26392an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 26393because the required size includes @code{Positive'Last} 26394bytes. As the first example indicates, the proper approach is to declare an 26395index type of 'reasonable' range so that unconstrained objects are not too 26396large. 26397 26398One final wrinkle: if the object is declared to be @code{aliased}, or if it is 26399created in the heap by means of an allocator, then it is @emph{not} 26400unconstrained: 26401it is constrained by the default values of the discriminants, and those values 26402cannot be modified by full assignment. This is because in the presence of 26403aliasing all views of the object (which may be manipulated by different tasks, 26404say) must be consistent, so it is imperative that the object, once created, 26405remain invariant. 26406 26407@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features 26408@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{42a}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{42b} 26409@section Strict Conformance to the Ada Reference Manual 26410 26411 26412The dynamic semantics defined by the Ada Reference Manual impose a set of 26413run-time checks to be generated. By default, the GNAT compiler will insert many 26414run-time checks into the compiled code, including most of those required by the 26415Ada Reference Manual. However, there are two checks that are not enabled in 26416the default mode for efficiency reasons: checks for access before elaboration 26417on subprogram calls, and stack overflow checking (most operating systems do not 26418perform this check by default). 26419 26420Strict conformance to the Ada Reference Manual can be achieved by adding two 26421compiler options for dynamic checks for access-before-elaboration on subprogram 26422calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 26423(@emph{-fstack-check}). 26424 26425Note that the result of a floating point arithmetic operation in overflow and 26426invalid situations, when the @code{Machine_Overflows} attribute of the result 26427type is @code{False}, is to generate IEEE NaN and infinite values. This is the 26428case for machines compliant with the IEEE floating-point standard, but on 26429machines that are not fully compliant with this standard, such as Alpha, the 26430@emph{-mieee} compiler flag must be used for achieving IEEE confirming 26431behavior (although at the cost of a significant performance penalty), so 26432infinite and NaN values are properly generated. 26433 26434@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top 26435@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{42c}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{42d} 26436@chapter Implementation of Ada 2012 Features 26437 26438 26439@geindex Ada 2012 implementation status 26440 26441@geindex -gnat12 option (gcc) 26442 26443@geindex pragma Ada_2012 26444 26445@geindex configuration pragma Ada_2012 26446 26447@geindex Ada_2012 configuration pragma 26448 26449This chapter contains a complete list of Ada 2012 features that have been 26450implemented. 26451Generally, these features are only 26452available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 26453which is the default behavior, 26454or if the configuration pragma @code{Ada_2012} is used. 26455 26456However, new pragmas, attributes, and restrictions are 26457unconditionally available, since the Ada 95 standard allows the addition of 26458new pragmas, attributes, and restrictions (there are exceptions, which are 26459documented in the individual descriptions), and also certain packages 26460were made available in earlier versions of Ada. 26461 26462An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 26463This date shows the implementation date of the feature. Any wavefront 26464subsequent to this date will contain the indicated feature, as will any 26465subsequent releases. A date of 0000-00-00 means that GNAT has always 26466implemented the feature, or implemented it as soon as it appeared as a 26467binding interpretation. 26468 26469Each feature corresponds to an Ada Issue ('AI') approved by the Ada 26470standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 26471The features are ordered based on the relevant sections of the Ada 26472Reference Manual ("RM"). When a given AI relates to multiple points 26473in the RM, the earliest is used. 26474 26475A complete description of the AIs may be found in 26476@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 26477 26478@geindex AI-0176 (Ada 2012 feature) 26479 26480 26481@itemize * 26482 26483@item 26484@emph{AI-0176 Quantified expressions (2010-09-29)} 26485 26486Both universally and existentially quantified expressions are implemented. 26487They use the new syntax for iterators proposed in AI05-139-2, as well as 26488the standard Ada loop syntax. 26489 26490RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 26491@end itemize 26492 26493@geindex AI-0079 (Ada 2012 feature) 26494 26495 26496@itemize * 26497 26498@item 26499@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 26500 26501Wide characters in the unicode category @emph{other_format} are now allowed in 26502source programs between tokens, but not within a token such as an identifier. 26503 26504RM References: 2.01 (4/2) 2.02 (7) 26505@end itemize 26506 26507@geindex AI-0091 (Ada 2012 feature) 26508 26509 26510@itemize * 26511 26512@item 26513@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 26514 26515Wide characters in the unicode category @emph{other_format} are not permitted 26516within an identifier, since this can be a security problem. The error 26517message for this case has been improved to be more specific, but GNAT has 26518never allowed such characters to appear in identifiers. 26519 26520RM 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) 26521@end itemize 26522 26523@geindex AI-0100 (Ada 2012 feature) 26524 26525 26526@itemize * 26527 26528@item 26529@emph{AI-0100 Placement of pragmas (2010-07-01)} 26530 26531This AI is an earlier version of AI-163. It simplifies the rules 26532for legal placement of pragmas. In the case of lists that allow pragmas, if 26533the list may have no elements, then the list may consist solely of pragmas. 26534 26535RM References: 2.08 (7) 26536@end itemize 26537 26538@geindex AI-0163 (Ada 2012 feature) 26539 26540 26541@itemize * 26542 26543@item 26544@emph{AI-0163 Pragmas in place of null (2010-07-01)} 26545 26546A statement sequence may be composed entirely of pragmas. It is no longer 26547necessary to add a dummy @code{null} statement to make the sequence legal. 26548 26549RM References: 2.08 (7) 2.08 (16) 26550@end itemize 26551 26552@geindex AI-0080 (Ada 2012 feature) 26553 26554 26555@itemize * 26556 26557@item 26558@emph{AI-0080 'View of' not needed if clear from context (0000-00-00)} 26559 26560This is an editorial change only, described as non-testable in the AI. 26561 26562RM References: 3.01 (7) 26563@end itemize 26564 26565@geindex AI-0183 (Ada 2012 feature) 26566 26567 26568@itemize * 26569 26570@item 26571@emph{AI-0183 Aspect specifications (2010-08-16)} 26572 26573Aspect specifications have been fully implemented except for pre and post- 26574conditions, and type invariants, which have their own separate AI's. All 26575forms of declarations listed in the AI are supported. The following is a 26576list of the aspects supported (with GNAT implementation aspects marked) 26577@end itemize 26578 26579 26580@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 26581@headitem 26582 26583Supported Aspect 26584 26585@tab 26586 26587Source 26588 26589@item 26590 26591@code{Ada_2005} 26592 26593@tab 26594 26595-- GNAT 26596 26597@item 26598 26599@code{Ada_2012} 26600 26601@tab 26602 26603-- GNAT 26604 26605@item 26606 26607@code{Address} 26608 26609@tab 26610 26611@item 26612 26613@code{Alignment} 26614 26615@tab 26616 26617@item 26618 26619@code{Atomic} 26620 26621@tab 26622 26623@item 26624 26625@code{Atomic_Components} 26626 26627@tab 26628 26629@item 26630 26631@code{Bit_Order} 26632 26633@tab 26634 26635@item 26636 26637@code{Component_Size} 26638 26639@tab 26640 26641@item 26642 26643@code{Contract_Cases} 26644 26645@tab 26646 26647-- GNAT 26648 26649@item 26650 26651@code{Discard_Names} 26652 26653@tab 26654 26655@item 26656 26657@code{External_Tag} 26658 26659@tab 26660 26661@item 26662 26663@code{Favor_Top_Level} 26664 26665@tab 26666 26667-- GNAT 26668 26669@item 26670 26671@code{Inline} 26672 26673@tab 26674 26675@item 26676 26677@code{Inline_Always} 26678 26679@tab 26680 26681-- GNAT 26682 26683@item 26684 26685@code{Invariant} 26686 26687@tab 26688 26689-- GNAT 26690 26691@item 26692 26693@code{Machine_Radix} 26694 26695@tab 26696 26697@item 26698 26699@code{No_Return} 26700 26701@tab 26702 26703@item 26704 26705@code{Object_Size} 26706 26707@tab 26708 26709-- GNAT 26710 26711@item 26712 26713@code{Pack} 26714 26715@tab 26716 26717@item 26718 26719@code{Persistent_BSS} 26720 26721@tab 26722 26723-- GNAT 26724 26725@item 26726 26727@code{Post} 26728 26729@tab 26730 26731@item 26732 26733@code{Pre} 26734 26735@tab 26736 26737@item 26738 26739@code{Predicate} 26740 26741@tab 26742 26743@item 26744 26745@code{Preelaborable_Initialization} 26746 26747@tab 26748 26749@item 26750 26751@code{Pure_Function} 26752 26753@tab 26754 26755-- GNAT 26756 26757@item 26758 26759@code{Remote_Access_Type} 26760 26761@tab 26762 26763-- GNAT 26764 26765@item 26766 26767@code{Shared} 26768 26769@tab 26770 26771-- GNAT 26772 26773@item 26774 26775@code{Size} 26776 26777@tab 26778 26779@item 26780 26781@code{Storage_Pool} 26782 26783@tab 26784 26785@item 26786 26787@code{Storage_Size} 26788 26789@tab 26790 26791@item 26792 26793@code{Stream_Size} 26794 26795@tab 26796 26797@item 26798 26799@code{Suppress} 26800 26801@tab 26802 26803@item 26804 26805@code{Suppress_Debug_Info} 26806 26807@tab 26808 26809-- GNAT 26810 26811@item 26812 26813@code{Test_Case} 26814 26815@tab 26816 26817-- GNAT 26818 26819@item 26820 26821@code{Thread_Local_Storage} 26822 26823@tab 26824 26825-- GNAT 26826 26827@item 26828 26829@code{Type_Invariant} 26830 26831@tab 26832 26833@item 26834 26835@code{Unchecked_Union} 26836 26837@tab 26838 26839@item 26840 26841@code{Universal_Aliasing} 26842 26843@tab 26844 26845-- GNAT 26846 26847@item 26848 26849@code{Unmodified} 26850 26851@tab 26852 26853-- GNAT 26854 26855@item 26856 26857@code{Unreferenced} 26858 26859@tab 26860 26861-- GNAT 26862 26863@item 26864 26865@code{Unreferenced_Objects} 26866 26867@tab 26868 26869-- GNAT 26870 26871@item 26872 26873@code{Unsuppress} 26874 26875@tab 26876 26877@item 26878 26879@code{Value_Size} 26880 26881@tab 26882 26883-- GNAT 26884 26885@item 26886 26887@code{Volatile} 26888 26889@tab 26890 26891@item 26892 26893@code{Volatile_Components} 26894 26895@tab 26896 26897@item 26898 26899@code{Warnings} 26900 26901@tab 26902 26903-- GNAT 26904 26905@end multitable 26906 26907 26908@quotation 26909 26910Note that for aspects with an expression, e.g. @code{Size}, the expression is 26911treated like a default expression (visibility is analyzed at the point of 26912occurrence of the aspect, but evaluation of the expression occurs at the 26913freeze point of the entity involved). 26914 26915RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 269163.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 26917(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 269189.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2691912.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2692013.03.01 (0) 26921@end quotation 26922 26923@geindex AI-0128 (Ada 2012 feature) 26924 26925 26926@itemize * 26927 26928@item 26929@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 26930 26931If an equality operator ("=") is declared for a type, then the implicitly 26932declared inequality operator ("/=") is a primitive operation of the type. 26933This is the only reasonable interpretation, and is the one always implemented 26934by GNAT, but the RM was not entirely clear in making this point. 26935 26936RM References: 3.02.03 (6) 6.06 (6) 26937@end itemize 26938 26939@geindex AI-0003 (Ada 2012 feature) 26940 26941 26942@itemize * 26943 26944@item 26945@emph{AI-0003 Qualified expressions as names (2010-07-11)} 26946 26947In Ada 2012, a qualified expression is considered to be syntactically a name, 26948meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 26949useful in disambiguating some cases of overloading. 26950 26951RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 269525.04 (7) 26953@end itemize 26954 26955@geindex AI-0120 (Ada 2012 feature) 26956 26957 26958@itemize * 26959 26960@item 26961@emph{AI-0120 Constant instance of protected object (0000-00-00)} 26962 26963This is an RM editorial change only. The section that lists objects that are 26964constant failed to include the current instance of a protected object 26965within a protected function. This has always been treated as a constant 26966in GNAT. 26967 26968RM References: 3.03 (21) 26969@end itemize 26970 26971@geindex AI-0008 (Ada 2012 feature) 26972 26973 26974@itemize * 26975 26976@item 26977@emph{AI-0008 General access to constrained objects (0000-00-00)} 26978 26979The wording in the RM implied that if you have a general access to a 26980constrained object, it could be used to modify the discriminants. This was 26981obviously not intended. @code{Constraint_Error} should be raised, and GNAT 26982has always done so in this situation. 26983 26984RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 26985@end itemize 26986 26987@geindex AI-0093 (Ada 2012 feature) 26988 26989 26990@itemize * 26991 26992@item 26993@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 26994 26995This is an editorial change only, to make more widespread use of the Ada 2012 26996'immutably limited'. 26997 26998RM References: 3.03 (23.4/3) 26999@end itemize 27000 27001@geindex AI-0096 (Ada 2012 feature) 27002 27003 27004@itemize * 27005 27006@item 27007@emph{AI-0096 Deriving from formal private types (2010-07-20)} 27008 27009In general it is illegal for a type derived from a formal limited type to be 27010nonlimited. This AI makes an exception to this rule: derivation is legal 27011if it appears in the private part of the generic, and the formal type is not 27012tagged. If the type is tagged, the legality check must be applied to the 27013private part of the package. 27014 27015RM References: 3.04 (5.1/2) 6.02 (7) 27016@end itemize 27017 27018@geindex AI-0181 (Ada 2012 feature) 27019 27020 27021@itemize * 27022 27023@item 27024@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 27025 27026From Ada 2005 on, soft hyphen is considered a non-graphic character, which 27027means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 27028@code{Image} and @code{Value} attributes for the character types. Strictly 27029speaking this is an inconsistency with Ada 95, but in practice the use of 27030these attributes is so obscure that it will not cause problems. 27031 27032RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 27033@end itemize 27034 27035@geindex AI-0182 (Ada 2012 feature) 27036 27037 27038@itemize * 27039 27040@item 27041@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} 27042 27043This AI allows @code{Character'Value} to accept the string @code{'?'} where 27044@code{?} is any character including non-graphic control characters. GNAT has 27045always accepted such strings. It also allows strings such as 27046@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 27047permission and raises @code{Constraint_Error}, as is certainly still 27048permitted. 27049 27050RM References: 3.05 (56/2) 27051@end itemize 27052 27053@geindex AI-0214 (Ada 2012 feature) 27054 27055 27056@itemize * 27057 27058@item 27059@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 27060 27061Ada 2012 relaxes the restriction that forbids discriminants of tagged types 27062to have default expressions by allowing them when the type is limited. It 27063is often useful to define a default value for a discriminant even though 27064it can't be changed by assignment. 27065 27066RM References: 3.07 (9.1/2) 3.07.02 (3) 27067@end itemize 27068 27069@geindex AI-0102 (Ada 2012 feature) 27070 27071 27072@itemize * 27073 27074@item 27075@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 27076 27077It is illegal to assign an anonymous access constant to an anonymous access 27078variable. The RM did not have a clear rule to prevent this, but GNAT has 27079always generated an error for this usage. 27080 27081RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 27082@end itemize 27083 27084@geindex AI-0158 (Ada 2012 feature) 27085 27086 27087@itemize * 27088 27089@item 27090@emph{AI-0158 Generalizing membership tests (2010-09-16)} 27091 27092This AI extends the syntax of membership tests to simplify complex conditions 27093that can be expressed as membership in a subset of values of any type. It 27094introduces syntax for a list of expressions that may be used in loop contexts 27095as well. 27096 27097RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 27098@end itemize 27099 27100@geindex AI-0173 (Ada 2012 feature) 27101 27102 27103@itemize * 27104 27105@item 27106@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 27107 27108The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 27109with the tag of an abstract type, and @code{False} otherwise. 27110 27111RM References: 3.09 (7.4/2) 3.09 (12.4/2) 27112@end itemize 27113 27114@geindex AI-0076 (Ada 2012 feature) 27115 27116 27117@itemize * 27118 27119@item 27120@emph{AI-0076 function with controlling result (0000-00-00)} 27121 27122This is an editorial change only. The RM defines calls with controlling 27123results, but uses the term 'function with controlling result' without an 27124explicit definition. 27125 27126RM References: 3.09.02 (2/2) 27127@end itemize 27128 27129@geindex AI-0126 (Ada 2012 feature) 27130 27131 27132@itemize * 27133 27134@item 27135@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 27136 27137This AI clarifies dispatching rules, and simply confirms that dispatching 27138executes the operation of the parent type when there is no explicitly or 27139implicitly declared operation for the descendant type. This has always been 27140the case in all versions of GNAT. 27141 27142RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 27143@end itemize 27144 27145@geindex AI-0097 (Ada 2012 feature) 27146 27147 27148@itemize * 27149 27150@item 27151@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 27152 27153The RM as written implied that in some cases it was possible to create an 27154object of an abstract type, by having an abstract extension inherit a non- 27155abstract constructor from its parent type. This mistake has been corrected 27156in GNAT and in the RM, and this construct is now illegal. 27157 27158RM References: 3.09.03 (4/2) 27159@end itemize 27160 27161@geindex AI-0203 (Ada 2012 feature) 27162 27163 27164@itemize * 27165 27166@item 27167@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 27168 27169A return_subtype_indication cannot denote an abstract subtype. GNAT has never 27170permitted such usage. 27171 27172RM References: 3.09.03 (8/3) 27173@end itemize 27174 27175@geindex AI-0198 (Ada 2012 feature) 27176 27177 27178@itemize * 27179 27180@item 27181@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 27182 27183This AI resolves a conflict between two rules involving inherited abstract 27184operations and predefined operators. If a derived numeric type inherits 27185an abstract operator, it overrides the predefined one. This interpretation 27186was always the one implemented in GNAT. 27187 27188RM References: 3.09.03 (4/3) 27189@end itemize 27190 27191@geindex AI-0073 (Ada 2012 feature) 27192 27193 27194@itemize * 27195 27196@item 27197@emph{AI-0073 Functions returning abstract types (2010-07-10)} 27198 27199This AI covers a number of issues regarding returning abstract types. In 27200particular generic functions cannot have abstract result types or access 27201result types designated an abstract type. There are some other cases which 27202are detailed in the AI. Note that this binding interpretation has not been 27203retrofitted to operate before Ada 2012 mode, since it caused a significant 27204number of regressions. 27205 27206RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 27207@end itemize 27208 27209@geindex AI-0070 (Ada 2012 feature) 27210 27211 27212@itemize * 27213 27214@item 27215@emph{AI-0070 Elaboration of interface types (0000-00-00)} 27216 27217This is an editorial change only, there are no testable consequences short of 27218checking for the absence of generated code for an interface declaration. 27219 27220RM References: 3.09.04 (18/2) 27221@end itemize 27222 27223@geindex AI-0208 (Ada 2012 feature) 27224 27225 27226@itemize * 27227 27228@item 27229@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 27230 27231The wording in the Ada 2005 RM concerning characteristics of incomplete views 27232was incorrect and implied that some programs intended to be legal were now 27233illegal. GNAT had never considered such programs illegal, so it has always 27234implemented the intent of this AI. 27235 27236RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 27237@end itemize 27238 27239@geindex AI-0162 (Ada 2012 feature) 27240 27241 27242@itemize * 27243 27244@item 27245@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 27246 27247Incomplete types are made more useful by allowing them to be completed by 27248private types and private extensions. 27249 27250RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 27251@end itemize 27252 27253@geindex AI-0098 (Ada 2012 feature) 27254 27255 27256@itemize * 27257 27258@item 27259@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 27260 27261An unintentional omission in the RM implied some inconsistent restrictions on 27262the use of anonymous access to subprogram values. These restrictions were not 27263intentional, and have never been enforced by GNAT. 27264 27265RM References: 3.10.01 (6) 3.10.01 (9.2/2) 27266@end itemize 27267 27268@geindex AI-0199 (Ada 2012 feature) 27269 27270 27271@itemize * 27272 27273@item 27274@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 27275 27276A choice list in a record aggregate can include several components of 27277(distinct) anonymous access types as long as they have matching designated 27278subtypes. 27279 27280RM References: 4.03.01 (16) 27281@end itemize 27282 27283@geindex AI-0220 (Ada 2012 feature) 27284 27285 27286@itemize * 27287 27288@item 27289@emph{AI-0220 Needed components for aggregates (0000-00-00)} 27290 27291This AI addresses a wording problem in the RM that appears to permit some 27292complex cases of aggregates with nonstatic discriminants. GNAT has always 27293implemented the intended semantics. 27294 27295RM References: 4.03.01 (17) 27296@end itemize 27297 27298@geindex AI-0147 (Ada 2012 feature) 27299 27300 27301@itemize * 27302 27303@item 27304@emph{AI-0147 Conditional expressions (2009-03-29)} 27305 27306Conditional expressions are permitted. The form of such an expression is: 27307 27308@example 27309(if expr then expr @{elsif expr then expr@} [else expr]) 27310@end example 27311 27312The parentheses can be omitted in contexts where parentheses are present 27313anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 27314clause is omitted, @strong{else} @emph{True} is assumed; 27315thus @code{(if A then B)} is a way to conveniently represent 27316@emph{(A implies B)} in standard logic. 27317 27318RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 273194.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 27320@end itemize 27321 27322@geindex AI-0037 (Ada 2012 feature) 27323 27324 27325@itemize * 27326 27327@item 27328@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 27329 27330This AI confirms that an association of the form @code{Indx => <>} in an 27331array aggregate must raise @code{Constraint_Error} if @code{Indx} 27332is out of range. The RM specified a range check on other associations, but 27333not when the value of the association was defaulted. GNAT has always inserted 27334a constraint check on the index value. 27335 27336RM References: 4.03.03 (29) 27337@end itemize 27338 27339@geindex AI-0123 (Ada 2012 feature) 27340 27341 27342@itemize * 27343 27344@item 27345@emph{AI-0123 Composability of equality (2010-04-13)} 27346 27347Equality of untagged record composes, so that the predefined equality for a 27348composite type that includes a component of some untagged record type 27349@code{R} uses the equality operation of @code{R} (which may be user-defined 27350or predefined). This makes the behavior of untagged records identical to that 27351of tagged types in this respect. 27352 27353This change is an incompatibility with previous versions of Ada, but it 27354corrects a non-uniformity that was often a source of confusion. Analysis of 27355a large number of industrial programs indicates that in those rare cases 27356where a composite type had an untagged record component with a user-defined 27357equality, either there was no use of the composite equality, or else the code 27358expected the same composability as for tagged types, and thus had a bug that 27359would be fixed by this change. 27360 27361RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 273628.05.04 (8) 27363@end itemize 27364 27365@geindex AI-0088 (Ada 2012 feature) 27366 27367 27368@itemize * 27369 27370@item 27371@emph{AI-0088 The value of exponentiation (0000-00-00)} 27372 27373This AI clarifies the equivalence rule given for the dynamic semantics of 27374exponentiation: the value of the operation can be obtained by repeated 27375multiplication, but the operation can be implemented otherwise (for example 27376using the familiar divide-by-two-and-square algorithm, even if this is less 27377accurate), and does not imply repeated reads of a volatile base. 27378 27379RM References: 4.05.06 (11) 27380@end itemize 27381 27382@geindex AI-0188 (Ada 2012 feature) 27383 27384 27385@itemize * 27386 27387@item 27388@emph{AI-0188 Case expressions (2010-01-09)} 27389 27390Case expressions are permitted. This allows use of constructs such as: 27391 27392@example 27393X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 27394@end example 27395 27396RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 27397@end itemize 27398 27399@geindex AI-0104 (Ada 2012 feature) 27400 27401 27402@itemize * 27403 27404@item 27405@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 27406 27407The assignment @code{Ptr := new not null Some_Ptr;} will raise 27408@code{Constraint_Error} because the default value of the allocated object is 27409@strong{null}. This useless construct is illegal in Ada 2012. 27410 27411RM References: 4.08 (2) 27412@end itemize 27413 27414@geindex AI-0157 (Ada 2012 feature) 27415 27416 27417@itemize * 27418 27419@item 27420@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 27421 27422Allocation and Deallocation from an empty storage pool (i.e. allocation or 27423deallocation of a pointer for which a static storage size clause of zero 27424has been given) is now illegal and is detected as such. GNAT 27425previously gave a warning but not an error. 27426 27427RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 27428@end itemize 27429 27430@geindex AI-0179 (Ada 2012 feature) 27431 27432 27433@itemize * 27434 27435@item 27436@emph{AI-0179 Statement not required after label (2010-04-10)} 27437 27438It is not necessary to have a statement following a label, so a label 27439can appear at the end of a statement sequence without the need for putting a 27440null statement afterwards, but it is not allowable to have only labels and 27441no real statements in a statement sequence. 27442 27443RM References: 5.01 (2) 27444@end itemize 27445 27446@geindex AI-0139-2 (Ada 2012 feature) 27447 27448 27449@itemize * 27450 27451@item 27452@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 27453 27454The new syntax for iterating over arrays and containers is now implemented. 27455Iteration over containers is for now limited to read-only iterators. Only 27456default iterators are supported, with the syntax: @code{for Elem of C}. 27457 27458RM References: 5.05 27459@end itemize 27460 27461@geindex AI-0134 (Ada 2012 feature) 27462 27463 27464@itemize * 27465 27466@item 27467@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 27468 27469For full conformance, the profiles of anonymous-access-to-subprogram 27470parameters must match. GNAT has always enforced this rule. 27471 27472RM References: 6.03.01 (18) 27473@end itemize 27474 27475@geindex AI-0207 (Ada 2012 feature) 27476 27477 27478@itemize * 27479 27480@item 27481@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 27482 27483This AI confirms that access_to_constant indication must match for mode 27484conformance. This was implemented in GNAT when the qualifier was originally 27485introduced in Ada 2005. 27486 27487RM References: 6.03.01 (16/2) 27488@end itemize 27489 27490@geindex AI-0046 (Ada 2012 feature) 27491 27492 27493@itemize * 27494 27495@item 27496@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 27497 27498For full conformance, in the case of access parameters, the null exclusion 27499must match (either both or neither must have @code{not null}). 27500 27501RM References: 6.03.02 (18) 27502@end itemize 27503 27504@geindex AI-0118 (Ada 2012 feature) 27505 27506 27507@itemize * 27508 27509@item 27510@emph{AI-0118 The association of parameter associations (0000-00-00)} 27511 27512This AI clarifies the rules for named associations in subprogram calls and 27513generic instantiations. The rules have been in place since Ada 83. 27514 27515RM References: 6.04.01 (2) 12.03 (9) 27516@end itemize 27517 27518@geindex AI-0196 (Ada 2012 feature) 27519 27520 27521@itemize * 27522 27523@item 27524@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 27525 27526Null exclusion checks are not made for @code{out} parameters when 27527evaluating the actual parameters. GNAT has never generated these checks. 27528 27529RM References: 6.04.01 (13) 27530@end itemize 27531 27532@geindex AI-0015 (Ada 2012 feature) 27533 27534 27535@itemize * 27536 27537@item 27538@emph{AI-0015 Constant return objects (0000-00-00)} 27539 27540The return object declared in an @emph{extended_return_statement} may be 27541declared constant. This was always intended, and GNAT has always allowed it. 27542 27543RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 275446.05 (5.7/2) 27545@end itemize 27546 27547@geindex AI-0032 (Ada 2012 feature) 27548 27549 27550@itemize * 27551 27552@item 27553@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 27554 27555If a function returns a class-wide type, the object of an extended return 27556statement can be declared with a specific type that is covered by the class- 27557wide type. This has been implemented in GNAT since the introduction of 27558extended returns. Note AI-0103 complements this AI by imposing matching 27559rules for constrained return types. 27560 27561RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 275626.05 (8/2) 27563@end itemize 27564 27565@geindex AI-0103 (Ada 2012 feature) 27566 27567 27568@itemize * 27569 27570@item 27571@emph{AI-0103 Static matching for extended return (2010-07-23)} 27572 27573If the return subtype of a function is an elementary type or a constrained 27574type, the subtype indication in an extended return statement must match 27575statically this return subtype. 27576 27577RM References: 6.05 (5.2/2) 27578@end itemize 27579 27580@geindex AI-0058 (Ada 2012 feature) 27581 27582 27583@itemize * 27584 27585@item 27586@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 27587 27588The RM had some incorrect wording implying wrong treatment of abnormal 27589completion in an extended return. GNAT has always implemented the intended 27590correct semantics as described by this AI. 27591 27592RM References: 6.05 (22/2) 27593@end itemize 27594 27595@geindex AI-0050 (Ada 2012 feature) 27596 27597 27598@itemize * 27599 27600@item 27601@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 27602 27603The implementation permissions for raising @code{Constraint_Error} early on a function call 27604when it was clear an exception would be raised were over-permissive and allowed 27605mishandling of discriminants in some cases. GNAT did 27606not take advantage of these incorrect permissions in any case. 27607 27608RM References: 6.05 (24/2) 27609@end itemize 27610 27611@geindex AI-0125 (Ada 2012 feature) 27612 27613 27614@itemize * 27615 27616@item 27617@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 27618 27619In Ada 2012, the declaration of a primitive operation of a type extension 27620or private extension can also override an inherited primitive that is not 27621visible at the point of this declaration. 27622 27623RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 27624@end itemize 27625 27626@geindex AI-0062 (Ada 2012 feature) 27627 27628 27629@itemize * 27630 27631@item 27632@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 27633 27634A full constant may have a null exclusion even if its associated deferred 27635constant does not. GNAT has always allowed this. 27636 27637RM References: 7.04 (6/2) 7.04 (7.1/2) 27638@end itemize 27639 27640@geindex AI-0178 (Ada 2012 feature) 27641 27642 27643@itemize * 27644 27645@item 27646@emph{AI-0178 Incomplete views are limited (0000-00-00)} 27647 27648This AI clarifies the role of incomplete views and plugs an omission in the 27649RM. GNAT always correctly restricted the use of incomplete views and types. 27650 27651RM References: 7.05 (3/2) 7.05 (6/2) 27652@end itemize 27653 27654@geindex AI-0087 (Ada 2012 feature) 27655 27656 27657@itemize * 27658 27659@item 27660@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 27661 27662The actual for a formal nonlimited derived type cannot be limited. In 27663particular, a formal derived type that extends a limited interface but which 27664is not explicitly limited cannot be instantiated with a limited type. 27665 27666RM References: 7.05 (5/2) 12.05.01 (5.1/2) 27667@end itemize 27668 27669@geindex AI-0099 (Ada 2012 feature) 27670 27671 27672@itemize * 27673 27674@item 27675@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 27676 27677This AI clarifies that 'needs finalization' is part of dynamic semantics, 27678and therefore depends on the run-time characteristics of an object (i.e. its 27679tag) and not on its nominal type. As the AI indicates: "we do not expect 27680this to affect any implementation'@w{'}. 27681 27682RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 27683@end itemize 27684 27685@geindex AI-0064 (Ada 2012 feature) 27686 27687 27688@itemize * 27689 27690@item 27691@emph{AI-0064 Redundant finalization rule (0000-00-00)} 27692 27693This is an editorial change only. The intended behavior is already checked 27694by an existing ACATS test, which GNAT has always executed correctly. 27695 27696RM References: 7.06.01 (17.1/1) 27697@end itemize 27698 27699@geindex AI-0026 (Ada 2012 feature) 27700 27701 27702@itemize * 27703 27704@item 27705@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 27706 27707Record representation clauses concerning Unchecked_Union types cannot mention 27708the discriminant of the type. The type of a component declared in the variant 27709part of an Unchecked_Union cannot be controlled, have controlled components, 27710nor have protected or task parts. If an Unchecked_Union type is declared 27711within the body of a generic unit or its descendants, then the type of a 27712component declared in the variant part cannot be a formal private type or a 27713formal private extension declared within the same generic unit. 27714 27715RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 27716@end itemize 27717 27718@geindex AI-0205 (Ada 2012 feature) 27719 27720 27721@itemize * 27722 27723@item 27724@emph{AI-0205 Extended return declares visible name (0000-00-00)} 27725 27726This AI corrects a simple omission in the RM. Return objects have always 27727been visible within an extended return statement. 27728 27729RM References: 8.03 (17) 27730@end itemize 27731 27732@geindex AI-0042 (Ada 2012 feature) 27733 27734 27735@itemize * 27736 27737@item 27738@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 27739 27740This AI fixes a wording gap in the RM. An operation of a synchronized 27741interface can be implemented by a protected or task entry, but the abstract 27742operation is not being overridden in the usual sense, and it must be stated 27743separately that this implementation is legal. This has always been the case 27744in GNAT. 27745 27746RM References: 9.01 (9.2/2) 9.04 (11.1/2) 27747@end itemize 27748 27749@geindex AI-0030 (Ada 2012 feature) 27750 27751 27752@itemize * 27753 27754@item 27755@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 27756 27757Requeue is permitted to a protected, synchronized or task interface primitive 27758providing it is known that the overriding operation is an entry. Otherwise 27759the requeue statement has the same effect as a procedure call. Use of pragma 27760@code{Implemented} provides a way to impose a static requirement on the 27761overriding operation by adhering to one of the implementation kinds: entry, 27762protected procedure or any of the above. 27763 27764RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 277659.05.04 (6) 9.05.04 (7) 9.05.04 (12) 27766@end itemize 27767 27768@geindex AI-0201 (Ada 2012 feature) 27769 27770 27771@itemize * 27772 27773@item 27774@emph{AI-0201 Independence of atomic object components (2010-07-22)} 27775 27776If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 27777attribute, then individual components may not be addressable by independent 27778tasks. However, if the representation clause has no effect (is confirming), 27779then independence is not compromised. Furthermore, in GNAT, specification of 27780other appropriately addressable component sizes (e.g. 16 for 8-bit 27781characters) also preserves independence. GNAT now gives very clear warnings 27782both for the declaration of such a type, and for any assignment to its components. 27783 27784RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 27785@end itemize 27786 27787@geindex AI-0009 (Ada 2012 feature) 27788 27789 27790@itemize * 27791 27792@item 27793@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 27794 27795This AI introduces the new pragmas @code{Independent} and 27796@code{Independent_Components}, 27797which control guaranteeing independence of access to objects and components. 27798The AI also requires independence not unaffected by confirming rep clauses. 27799 27800RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 27801C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 27802@end itemize 27803 27804@geindex AI-0072 (Ada 2012 feature) 27805 27806 27807@itemize * 27808 27809@item 27810@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 27811 27812This AI clarifies that task signalling for reading @code{'Terminated} only 27813occurs if the result is True. GNAT semantics has always been consistent with 27814this notion of task signalling. 27815 27816RM References: 9.10 (6.1/1) 27817@end itemize 27818 27819@geindex AI-0108 (Ada 2012 feature) 27820 27821 27822@itemize * 27823 27824@item 27825@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 27826 27827This AI confirms that an incomplete type from a limited view does not have 27828discriminants. This has always been the case in GNAT. 27829 27830RM References: 10.01.01 (12.3/2) 27831@end itemize 27832 27833@geindex AI-0129 (Ada 2012 feature) 27834 27835 27836@itemize * 27837 27838@item 27839@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 27840 27841This AI clarifies the description of limited views: a limited view of a 27842package includes only one view of a type that has an incomplete declaration 27843and a full declaration (there is no possible ambiguity in a client package). 27844This AI also fixes an omission: a nested package in the private part has no 27845limited view. GNAT always implemented this correctly. 27846 27847RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 27848@end itemize 27849 27850@geindex AI-0077 (Ada 2012 feature) 27851 27852 27853@itemize * 27854 27855@item 27856@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 27857 27858This AI clarifies that a declaration does not include a context clause, 27859and confirms that it is illegal to have a context in which both a limited 27860and a nonlimited view of a package are accessible. Such double visibility 27861was always rejected by GNAT. 27862 27863RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 27864@end itemize 27865 27866@geindex AI-0122 (Ada 2012 feature) 27867 27868 27869@itemize * 27870 27871@item 27872@emph{AI-0122 Private with and children of generics (0000-00-00)} 27873 27874This AI clarifies the visibility of private children of generic units within 27875instantiations of a parent. GNAT has always handled this correctly. 27876 27877RM References: 10.01.02 (12/2) 27878@end itemize 27879 27880@geindex AI-0040 (Ada 2012 feature) 27881 27882 27883@itemize * 27884 27885@item 27886@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 27887 27888This AI confirms that a limited with clause in a child unit cannot name 27889an ancestor of the unit. This has always been checked in GNAT. 27890 27891RM References: 10.01.02 (20/2) 27892@end itemize 27893 27894@geindex AI-0132 (Ada 2012 feature) 27895 27896 27897@itemize * 27898 27899@item 27900@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 27901 27902This AI fills a gap in the description of library unit pragmas. The pragma 27903clearly must apply to a library unit, even if it does not carry the name 27904of the enclosing unit. GNAT has always enforced the required check. 27905 27906RM References: 10.01.05 (7) 27907@end itemize 27908 27909@geindex AI-0034 (Ada 2012 feature) 27910 27911 27912@itemize * 27913 27914@item 27915@emph{AI-0034 Categorization of limited views (0000-00-00)} 27916 27917The RM makes certain limited with clauses illegal because of categorization 27918considerations, when the corresponding normal with would be legal. This is 27919not intended, and GNAT has always implemented the recommended behavior. 27920 27921RM References: 10.02.01 (11/1) 10.02.01 (17/2) 27922@end itemize 27923 27924@geindex AI-0035 (Ada 2012 feature) 27925 27926 27927@itemize * 27928 27929@item 27930@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 27931 27932This AI remedies some inconsistencies in the legality rules for Pure units. 27933Derived access types are legal in a pure unit (on the assumption that the 27934rule for a zero storage pool size has been enforced on the ancestor type). 27935The rules are enforced in generic instances and in subunits. GNAT has always 27936implemented the recommended behavior. 27937 27938RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 27939@end itemize 27940 27941@geindex AI-0219 (Ada 2012 feature) 27942 27943 27944@itemize * 27945 27946@item 27947@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 27948 27949This AI refines the rules for the cases with limited parameters which do not 27950allow the implementations to omit 'redundant'. GNAT now properly conforms 27951to the requirements of this binding interpretation. 27952 27953RM References: 10.02.01 (18/2) 27954@end itemize 27955 27956@geindex AI-0043 (Ada 2012 feature) 27957 27958 27959@itemize * 27960 27961@item 27962@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 27963 27964This AI covers various omissions in the RM regarding the raising of 27965exceptions. GNAT has always implemented the intended semantics. 27966 27967RM References: 11.04.01 (10.1/2) 11 (2) 27968@end itemize 27969 27970@geindex AI-0200 (Ada 2012 feature) 27971 27972 27973@itemize * 27974 27975@item 27976@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 27977 27978This AI plugs a gap in the RM which appeared to allow some obviously intended 27979illegal instantiations. GNAT has never allowed these instantiations. 27980 27981RM References: 12.07 (16) 27982@end itemize 27983 27984@geindex AI-0112 (Ada 2012 feature) 27985 27986 27987@itemize * 27988 27989@item 27990@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 27991 27992This AI concerns giving names to various representation aspects, but the 27993practical effect is simply to make the use of duplicate 27994@code{Atomic[_Components]}, 27995@code{Volatile[_Components]}, and 27996@code{Independent[_Components]} pragmas illegal, and GNAT 27997now performs this required check. 27998 27999RM References: 13.01 (8) 28000@end itemize 28001 28002@geindex AI-0106 (Ada 2012 feature) 28003 28004 28005@itemize * 28006 28007@item 28008@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 28009 28010The RM appeared to allow representation pragmas on generic formal parameters, 28011but this was not intended, and GNAT has never permitted this usage. 28012 28013RM References: 13.01 (9.1/1) 28014@end itemize 28015 28016@geindex AI-0012 (Ada 2012 feature) 28017 28018 28019@itemize * 28020 28021@item 28022@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 28023 28024It is now illegal to give an inappropriate component size or a pragma 28025@code{Pack} that attempts to change the component size in the case of atomic 28026or aliased components. Previously GNAT ignored such an attempt with a 28027warning. 28028 28029RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 28030@end itemize 28031 28032@geindex AI-0039 (Ada 2012 feature) 28033 28034 28035@itemize * 28036 28037@item 28038@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 28039 28040The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 28041for stream attributes, but these were never useful and are now illegal. GNAT 28042has always regarded such expressions as illegal. 28043 28044RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 28045@end itemize 28046 28047@geindex AI-0095 (Ada 2012 feature) 28048 28049 28050@itemize * 28051 28052@item 28053@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 28054 28055The prefix of @code{'Address} cannot statically denote a subprogram with 28056convention @code{Intrinsic}. The use of the @code{Address} attribute raises 28057@code{Program_Error} if the prefix denotes a subprogram with convention 28058@code{Intrinsic}. 28059 28060RM References: 13.03 (11/1) 28061@end itemize 28062 28063@geindex AI-0116 (Ada 2012 feature) 28064 28065 28066@itemize * 28067 28068@item 28069@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 28070 28071This AI requires that the alignment of a class-wide object be no greater 28072than the alignment of any type in the class. GNAT has always followed this 28073recommendation. 28074 28075RM References: 13.03 (29) 13.11 (16) 28076@end itemize 28077 28078@geindex AI-0146 (Ada 2012 feature) 28079 28080 28081@itemize * 28082 28083@item 28084@emph{AI-0146 Type invariants (2009-09-21)} 28085 28086Type invariants may be specified for private types using the aspect notation. 28087Aspect @code{Type_Invariant} may be specified for any private type, 28088@code{Type_Invariant'Class} can 28089only be specified for tagged types, and is inherited by any descendent of the 28090tagged types. The invariant is a boolean expression that is tested for being 28091true in the following situations: conversions to the private type, object 28092declarations for the private type that are default initialized, and 28093[@strong{in}] @strong{out} 28094parameters and returned result on return from any primitive operation for 28095the type that is visible to a client. 28096GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 28097@code{Invariant'Class} for @code{Type_Invariant'Class}. 28098 28099RM References: 13.03.03 (00) 28100@end itemize 28101 28102@geindex AI-0078 (Ada 2012 feature) 28103 28104 28105@itemize * 28106 28107@item 28108@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 28109 28110In Ada 2012, compilers are required to support unchecked conversion where the 28111target alignment is a multiple of the source alignment. GNAT always supported 28112this case (and indeed all cases of differing alignments, doing copies where 28113required if the alignment was reduced). 28114 28115RM References: 13.09 (7) 28116@end itemize 28117 28118@geindex AI-0195 (Ada 2012 feature) 28119 28120 28121@itemize * 28122 28123@item 28124@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 28125 28126The handling of invalid values is now designated to be implementation 28127defined. This is a documentation change only, requiring Annex M in the GNAT 28128Reference Manual to document this handling. 28129In GNAT, checks for invalid values are made 28130only when necessary to avoid erroneous behavior. Operations like assignments 28131which cannot cause erroneous behavior ignore the possibility of invalid 28132values and do not do a check. The date given above applies only to the 28133documentation change, this behavior has always been implemented by GNAT. 28134 28135RM References: 13.09.01 (10) 28136@end itemize 28137 28138@geindex AI-0193 (Ada 2012 feature) 28139 28140 28141@itemize * 28142 28143@item 28144@emph{AI-0193 Alignment of allocators (2010-09-16)} 28145 28146This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 28147analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 28148of size. 28149 28150RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2815113.11.01 (2) 13.11.01 (3) 28152@end itemize 28153 28154@geindex AI-0177 (Ada 2012 feature) 28155 28156 28157@itemize * 28158 28159@item 28160@emph{AI-0177 Parameterized expressions (2010-07-10)} 28161 28162The new Ada 2012 notion of parameterized expressions is implemented. The form 28163is: 28164 28165@example 28166function-specification is (expression) 28167@end example 28168 28169This is exactly equivalent to the 28170corresponding function body that returns the expression, but it can appear 28171in a package spec. Note that the expression must be parenthesized. 28172 28173RM References: 13.11.01 (3/2) 28174@end itemize 28175 28176@geindex AI-0033 (Ada 2012 feature) 28177 28178 28179@itemize * 28180 28181@item 28182@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 28183 28184Neither of these two pragmas may appear within a generic template, because 28185the generic might be instantiated at other than the library level. 28186 28187RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 28188@end itemize 28189 28190@geindex AI-0161 (Ada 2012 feature) 28191 28192 28193@itemize * 28194 28195@item 28196@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 28197 28198A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 28199of the default stream attributes for elementary types. If this restriction is 28200in force, then it is necessary to provide explicit subprograms for any 28201stream attributes used. 28202 28203RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 28204@end itemize 28205 28206@geindex AI-0194 (Ada 2012 feature) 28207 28208 28209@itemize * 28210 28211@item 28212@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 28213 28214The @code{Stream_Size} attribute returns the default number of bits in the 28215stream representation of the given type. 28216This value is not affected by the presence 28217of stream subprogram attributes for the type. GNAT has always implemented 28218this interpretation. 28219 28220RM References: 13.13.02 (1.2/2) 28221@end itemize 28222 28223@geindex AI-0109 (Ada 2012 feature) 28224 28225 28226@itemize * 28227 28228@item 28229@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 28230 28231This AI is an editorial change only. It removes the need for a tag check 28232that can never fail. 28233 28234RM References: 13.13.02 (34/2) 28235@end itemize 28236 28237@geindex AI-0007 (Ada 2012 feature) 28238 28239 28240@itemize * 28241 28242@item 28243@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 28244 28245The RM as written appeared to limit the possibilities of declaring read 28246attribute procedures for private scalar types. This limitation was not 28247intended, and has never been enforced by GNAT. 28248 28249RM References: 13.13.02 (50/2) 13.13.02 (51/2) 28250@end itemize 28251 28252@geindex AI-0065 (Ada 2012 feature) 28253 28254 28255@itemize * 28256 28257@item 28258@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 28259 28260This AI clarifies the fact that all remote access types support external 28261streaming. This fixes an obvious oversight in the definition of the 28262language, and GNAT always implemented the intended correct rules. 28263 28264RM References: 13.13.02 (52/2) 28265@end itemize 28266 28267@geindex AI-0019 (Ada 2012 feature) 28268 28269 28270@itemize * 28271 28272@item 28273@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 28274 28275The RM suggests that primitive subprograms of a specific tagged type are 28276frozen when the tagged type is frozen. This would be an incompatible change 28277and is not intended. GNAT has never attempted this kind of freezing and its 28278behavior is consistent with the recommendation of this AI. 28279 28280RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 28281@end itemize 28282 28283@geindex AI-0017 (Ada 2012 feature) 28284 28285 28286@itemize * 28287 28288@item 28289@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 28290 28291So-called 'Taft-amendment types' (i.e., types that are completed in package 28292bodies) are not frozen by the occurrence of bodies in the 28293enclosing declarative part. GNAT always implemented this properly. 28294 28295RM References: 13.14 (3/1) 28296@end itemize 28297 28298@geindex AI-0060 (Ada 2012 feature) 28299 28300 28301@itemize * 28302 28303@item 28304@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 28305 28306This AI extends the definition of remote access types to include access 28307to limited, synchronized, protected or task class-wide interface types. 28308GNAT already implemented this extension. 28309 28310RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 28311@end itemize 28312 28313@geindex AI-0114 (Ada 2012 feature) 28314 28315 28316@itemize * 28317 28318@item 28319@emph{AI-0114 Classification of letters (0000-00-00)} 28320 28321The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 28322181 (@code{MICRO SIGN}), and 28323186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 28324lower case letters by Unicode. 28325However, they are not allowed in identifiers, and they 28326return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 28327This behavior is consistent with that defined in Ada 95. 28328 28329RM References: A.03.02 (59) A.04.06 (7) 28330@end itemize 28331 28332@geindex AI-0185 (Ada 2012 feature) 28333 28334 28335@itemize * 28336 28337@item 28338@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 28339 28340Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 28341classification functions for @code{Wide_Character} and 28342@code{Wide_Wide_Character}, as well as providing 28343case folding routines for @code{Wide_[Wide_]Character} and 28344@code{Wide_[Wide_]String}. 28345 28346RM References: A.03.05 (0) A.03.06 (0) 28347@end itemize 28348 28349@geindex AI-0031 (Ada 2012 feature) 28350 28351 28352@itemize * 28353 28354@item 28355@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 28356 28357A new version of @code{Find_Token} is added to all relevant string packages, 28358with an extra parameter @code{From}. Instead of starting at the first 28359character of the string, the search for a matching Token starts at the 28360character indexed by the value of @code{From}. 28361These procedures are available in all versions of Ada 28362but if used in versions earlier than Ada 2012 they will generate a warning 28363that an Ada 2012 subprogram is being used. 28364 28365RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 28366A.04.05 (46) 28367@end itemize 28368 28369@geindex AI-0056 (Ada 2012 feature) 28370 28371 28372@itemize * 28373 28374@item 28375@emph{AI-0056 Index on null string returns zero (0000-00-00)} 28376 28377The wording in the Ada 2005 RM implied an incompatible handling of the 28378@code{Index} functions, resulting in raising an exception instead of 28379returning zero in some situations. 28380This was not intended and has been corrected. 28381GNAT always returned zero, and is thus consistent with this AI. 28382 28383RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 28384@end itemize 28385 28386@geindex AI-0137 (Ada 2012 feature) 28387 28388 28389@itemize * 28390 28391@item 28392@emph{AI-0137 String encoding package (2010-03-25)} 28393 28394The packages @code{Ada.Strings.UTF_Encoding}, together with its child 28395packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 28396and @code{Wide_Wide_Strings} have been 28397implemented. These packages (whose documentation can be found in the spec 28398files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 28399@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 28400@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 28401values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 28402UTF-16), as well as conversions between the different UTF encodings. With 28403the exception of @code{Wide_Wide_Strings}, these packages are available in 28404Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 28405The @code{Wide_Wide_Strings} package 28406is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 28407mode since it uses @code{Wide_Wide_Character}). 28408 28409RM References: A.04.11 28410@end itemize 28411 28412@geindex AI-0038 (Ada 2012 feature) 28413 28414 28415@itemize * 28416 28417@item 28418@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 28419 28420These are minor errors in the description on three points. The intent on 28421all these points has always been clear, and GNAT has always implemented the 28422correct intended semantics. 28423 28424RM 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) 28425@end itemize 28426 28427@geindex AI-0044 (Ada 2012 feature) 28428 28429 28430@itemize * 28431 28432@item 28433@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 28434 28435This AI places restrictions on allowed instantiations of generic containers. 28436These restrictions are not checked by the compiler, so there is nothing to 28437change in the implementation. This affects only the RM documentation. 28438 28439RM 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) 28440@end itemize 28441 28442@geindex AI-0127 (Ada 2012 feature) 28443 28444 28445@itemize * 28446 28447@item 28448@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 28449 28450This package provides an interface for identifying the current locale. 28451 28452RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 28453A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 28454@end itemize 28455 28456@geindex AI-0002 (Ada 2012 feature) 28457 28458 28459@itemize * 28460 28461@item 28462@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 28463 28464The compiler is not required to support exporting an Ada subprogram with 28465convention C if there are parameters or a return type of an unconstrained 28466array type (such as @code{String}). GNAT allows such declarations but 28467generates warnings. It is possible, but complicated, to write the 28468corresponding C code and certainly such code would be specific to GNAT and 28469non-portable. 28470 28471RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 28472@end itemize 28473 28474@geindex AI05-0216 (Ada 2012 feature) 28475 28476 28477@itemize * 28478 28479@item 28480@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 28481 28482It is clearly the intention that @code{No_Task_Hierarchy} is intended to 28483forbid tasks declared locally within subprograms, or functions returning task 28484objects, and that is the implementation that GNAT has always provided. 28485However the language in the RM was not sufficiently clear on this point. 28486Thus this is a documentation change in the RM only. 28487 28488RM References: D.07 (3/3) 28489@end itemize 28490 28491@geindex AI-0211 (Ada 2012 feature) 28492 28493 28494@itemize * 28495 28496@item 28497@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 28498 28499The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 28500@code{Ada.Real_Time.Timing_Events.Set_Handler}. 28501 28502RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 28503@end itemize 28504 28505@geindex AI-0190 (Ada 2012 feature) 28506 28507 28508@itemize * 28509 28510@item 28511@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 28512 28513This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 28514used to control storage pools globally. 28515In particular, you can force every access 28516type that is used for allocation (@strong{new}) to have an explicit storage pool, 28517or you can declare a pool globally to be used for all access types that lack 28518an explicit one. 28519 28520RM References: D.07 (8) 28521@end itemize 28522 28523@geindex AI-0189 (Ada 2012 feature) 28524 28525 28526@itemize * 28527 28528@item 28529@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 28530 28531This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 28532which says that no dynamic allocation will occur once elaboration is 28533completed. 28534In general this requires a run-time check, which is not required, and which 28535GNAT does not attempt. But the static cases of allocators in a task body or 28536in the body of the main program are detected and flagged at compile or bind 28537time. 28538 28539RM References: D.07 (19.1/2) H.04 (23.3/2) 28540@end itemize 28541 28542@geindex AI-0171 (Ada 2012 feature) 28543 28544 28545@itemize * 28546 28547@item 28548@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 28549 28550A new package @code{System.Multiprocessors} is added, together with the 28551definition of pragma @code{CPU} for controlling task affinity. A new no 28552dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 28553is added to the Ravenscar profile. 28554 28555RM References: D.13.01 (4/2) D.16 28556@end itemize 28557 28558@geindex AI-0210 (Ada 2012 feature) 28559 28560 28561@itemize * 28562 28563@item 28564@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 28565 28566This is a documentation only issue regarding wording of metric requirements, 28567that does not affect the implementation of the compiler. 28568 28569RM References: D.15 (24/2) 28570@end itemize 28571 28572@geindex AI-0206 (Ada 2012 feature) 28573 28574 28575@itemize * 28576 28577@item 28578@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 28579 28580Remote types packages are now allowed to depend on preelaborated packages. 28581This was formerly considered illegal. 28582 28583RM References: E.02.02 (6) 28584@end itemize 28585 28586@geindex AI-0152 (Ada 2012 feature) 28587 28588 28589@itemize * 28590 28591@item 28592@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 28593 28594Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 28595where the type of the returned value is an anonymous access type. 28596 28597RM References: H.04 (8/1) 28598@end itemize 28599 28600@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top 28601@anchor{gnat_rm/obsolescent_features id1}@anchor{42e}@anchor{gnat_rm/obsolescent_features doc}@anchor{42f}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15} 28602@chapter Obsolescent Features 28603 28604 28605This chapter describes features that are provided by GNAT, but are 28606considered obsolescent since there are preferred ways of achieving 28607the same effect. These features are provided solely for historical 28608compatibility purposes. 28609 28610@menu 28611* pragma No_Run_Time:: 28612* pragma Ravenscar:: 28613* pragma Restricted_Run_Time:: 28614* pragma Task_Info:: 28615* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 28616 28617@end menu 28618 28619@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 28620@anchor{gnat_rm/obsolescent_features id2}@anchor{430}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{431} 28621@section pragma No_Run_Time 28622 28623 28624The pragma @code{No_Run_Time} is used to achieve an affect similar 28625to the use of the "Zero Foot Print" configurable run time, but without 28626requiring a specially configured run time. The result of using this 28627pragma, which must be used for all units in a partition, is to restrict 28628the use of any language features requiring run-time support code. The 28629preferred usage is to use an appropriately configured run-time that 28630includes just those features that are to be made accessible. 28631 28632@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 28633@anchor{gnat_rm/obsolescent_features id3}@anchor{432}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{433} 28634@section pragma Ravenscar 28635 28636 28637The pragma @code{Ravenscar} has exactly the same effect as pragma 28638@code{Profile (Ravenscar)}. The latter usage is preferred since it 28639is part of the new Ada 2005 standard. 28640 28641@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 28642@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{434}@anchor{gnat_rm/obsolescent_features id4}@anchor{435} 28643@section pragma Restricted_Run_Time 28644 28645 28646The pragma @code{Restricted_Run_Time} has exactly the same effect as 28647pragma @code{Profile (Restricted)}. The latter usage is 28648preferred since the Ada 2005 pragma @code{Profile} is intended for 28649this kind of implementation dependent addition. 28650 28651@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 28652@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{436}@anchor{gnat_rm/obsolescent_features id5}@anchor{437} 28653@section pragma Task_Info 28654 28655 28656The functionality provided by pragma @code{Task_Info} is now part of the 28657Ada language. The @code{CPU} aspect and the package 28658@code{System.Multiprocessors} offer a less system-dependent way to specify 28659task affinity or to query the number of processsors. 28660 28661Syntax 28662 28663@example 28664pragma Task_Info (EXPRESSION); 28665@end example 28666 28667This pragma appears within a task definition (like pragma 28668@code{Priority}) and applies to the task in which it appears. The 28669argument must be of type @code{System.Task_Info.Task_Info_Type}. 28670The @code{Task_Info} pragma provides system dependent control over 28671aspects of tasking implementation, for example, the ability to map 28672tasks to specific processors. For details on the facilities available 28673for the version of GNAT that you are using, see the documentation 28674in the spec of package System.Task_Info in the runtime 28675library. 28676 28677@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 28678@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{438}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{439} 28679@section package System.Task_Info (@code{s-tasinf.ads}) 28680 28681 28682This package provides target dependent functionality that is used 28683to support the @code{Task_Info} pragma. The predefined Ada package 28684@code{System.Multiprocessors} and the @code{CPU} aspect now provide a 28685standard replacement for GNAT's @code{Task_Info} functionality. 28686 28687@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 28688@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{43a}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{43b} 28689@chapter Compatibility and Porting Guide 28690 28691 28692This chapter presents some guidelines for developing portable Ada code, 28693describes the compatibility issues that may arise between 28694GNAT and other Ada compilation systems (including those for Ada 83), 28695and shows how GNAT can expedite porting 28696applications developed in other Ada environments. 28697 28698@menu 28699* Writing Portable Fixed-Point Declarations:: 28700* Compatibility with Ada 83:: 28701* Compatibility between Ada 95 and Ada 2005:: 28702* Implementation-dependent characteristics:: 28703* Compatibility with Other Ada Systems:: 28704* Representation Clauses:: 28705* Compatibility with HP Ada 83:: 28706 28707@end menu 28708 28709@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 28710@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{43c}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{43d} 28711@section Writing Portable Fixed-Point Declarations 28712 28713 28714The Ada Reference Manual gives an implementation freedom to choose bounds 28715that are narrower by @code{Small} from the given bounds. 28716For example, if we write 28717 28718@example 28719type F1 is delta 1.0 range -128.0 .. +128.0; 28720@end example 28721 28722then the implementation is allowed to choose -128.0 .. +127.0 if it 28723likes, but is not required to do so. 28724 28725This leads to possible portability problems, so let's have a closer 28726look at this, and figure out how to avoid these problems. 28727 28728First, why does this freedom exist, and why would an implementation 28729take advantage of it? To answer this, take a closer look at the type 28730declaration for @code{F1} above. If the compiler uses the given bounds, 28731it would need 9 bits to hold the largest positive value (and typically 28732that means 16 bits on all machines). But if the implementation chooses 28733the +127.0 bound then it can fit values of the type in 8 bits. 28734 28735Why not make the user write +127.0 if that's what is wanted? 28736The rationale is that if you are thinking of fixed point 28737as a kind of 'poor man's floating-point', then you don't want 28738to be thinking about the scaled integers that are used in its 28739representation. Let's take another example: 28740 28741@example 28742type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 28743@end example 28744 28745Looking at this declaration, it seems casually as though 28746it should fit in 16 bits, but again that extra positive value 28747+1.0 has the scaled integer equivalent of 2**15 which is one too 28748big for signed 16 bits. The implementation can treat this as: 28749 28750@example 28751type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 28752@end example 28753 28754and the Ada language design team felt that this was too annoying 28755to require. We don't need to debate this decision at this point, 28756since it is well established (the rule about narrowing the ranges 28757dates to Ada 83). 28758 28759But the important point is that an implementation is not required 28760to do this narrowing, so we have a potential portability problem. 28761We could imagine three types of implementation: 28762 28763 28764@enumerate a 28765 28766@item 28767those that narrow the range automatically if they can figure 28768out that the narrower range will allow storage in a smaller machine unit, 28769 28770@item 28771those that will narrow only if forced to by a @code{'Size} clause, and 28772 28773@item 28774those that will never narrow. 28775@end enumerate 28776 28777Now if we are language theoreticians, we can imagine a fourth 28778approach: to narrow all the time, e.g. to treat 28779 28780@example 28781type F3 is delta 1.0 range -10.0 .. +23.0; 28782@end example 28783 28784as though it had been written: 28785 28786@example 28787type F3 is delta 1.0 range -9.0 .. +22.0; 28788@end example 28789 28790But although technically allowed, such a behavior would be hostile and silly, 28791and no real compiler would do this. All real compilers will fall into one of 28792the categories (a), (b) or (c) above. 28793 28794So, how do you get the compiler to do what you want? The answer is give the 28795actual bounds you want, and then use a @code{'Small} clause and a 28796@code{'Size} clause to absolutely pin down what the compiler does. 28797E.g., for @code{F2} above, we will write: 28798 28799@example 28800My_Small : constant := 2.0**(-15); 28801My_First : constant := -1.0; 28802My_Last : constant := +1.0 - My_Small; 28803 28804type F2 is delta My_Small range My_First .. My_Last; 28805@end example 28806 28807and then add 28808 28809@example 28810for F2'Small use my_Small; 28811for F2'Size use 16; 28812@end example 28813 28814In practice all compilers will do the same thing here and will give you 28815what you want, so the above declarations are fully portable. If you really 28816want to play language lawyer and guard against ludicrous behavior by the 28817compiler you could add 28818 28819@example 28820Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 28821Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 28822@end example 28823 28824One or other or both are allowed to be illegal if the compiler is 28825behaving in a silly manner, but at least the silly compiler will not 28826get away with silently messing with your (very clear) intentions. 28827 28828If you follow this scheme you will be guaranteed that your fixed-point 28829types will be portable. 28830 28831@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 28832@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{43e}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{43f} 28833@section Compatibility with Ada 83 28834 28835 28836@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 28837 28838Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 28839are highly upwards compatible with Ada 83. In 28840particular, the design intention was that the difficulties associated 28841with moving from Ada 83 to later versions of the standard should be no greater 28842than those that occur when moving from one Ada 83 system to another. 28843 28844However, there are a number of points at which there are minor 28845incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 28846full details of these issues as they relate to Ada 95, 28847and should be consulted for a complete treatment. 28848In practice the 28849following subsections treat the most likely issues to be encountered. 28850 28851@menu 28852* Legal Ada 83 programs that are illegal in Ada 95:: 28853* More deterministic semantics:: 28854* Changed semantics:: 28855* Other language compatibility issues:: 28856 28857@end menu 28858 28859@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 28860@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{440}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{441} 28861@subsection Legal Ada 83 programs that are illegal in Ada 95 28862 28863 28864Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 28865Ada 95 and later versions of the standard: 28866 28867 28868@itemize * 28869 28870@item 28871@emph{Character literals} 28872 28873Some uses of character literals are ambiguous. Since Ada 95 has introduced 28874@code{Wide_Character} as a new predefined character type, some uses of 28875character literals that were legal in Ada 83 are illegal in Ada 95. 28876For example: 28877 28878@example 28879for Char in 'A' .. 'Z' loop ... end loop; 28880@end example 28881 28882The problem is that 'A' and 'Z' could be from either 28883@code{Character} or @code{Wide_Character}. The simplest correction 28884is to make the type explicit; e.g.: 28885 28886@example 28887for Char in Character range 'A' .. 'Z' loop ... end loop; 28888@end example 28889 28890@item 28891@emph{New reserved words} 28892 28893The identifiers @code{abstract}, @code{aliased}, @code{protected}, 28894@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. 28895Existing Ada 83 code using any of these identifiers must be edited to 28896use some alternative name. 28897 28898@item 28899@emph{Freezing rules} 28900 28901The rules in Ada 95 are slightly different with regard to the point at 28902which entities are frozen, and representation pragmas and clauses are 28903not permitted past the freeze point. This shows up most typically in 28904the form of an error message complaining that a representation item 28905appears too late, and the appropriate corrective action is to move 28906the item nearer to the declaration of the entity to which it refers. 28907 28908A particular case is that representation pragmas 28909cannot be applied to a subprogram body. If necessary, a separate subprogram 28910declaration must be introduced to which the pragma can be applied. 28911 28912@item 28913@emph{Optional bodies for library packages} 28914 28915In Ada 83, a package that did not require a package body was nevertheless 28916allowed to have one. This lead to certain surprises in compiling large 28917systems (situations in which the body could be unexpectedly ignored by the 28918binder). In Ada 95, if a package does not require a body then it is not 28919permitted to have a body. To fix this problem, simply remove a redundant 28920body if it is empty, or, if it is non-empty, introduce a dummy declaration 28921into the spec that makes the body required. One approach is to add a private 28922part to the package declaration (if necessary), and define a parameterless 28923procedure called @code{Requires_Body}, which must then be given a dummy 28924procedure body in the package body, which then becomes required. 28925Another approach (assuming that this does not introduce elaboration 28926circularities) is to add an @code{Elaborate_Body} pragma to the package spec, 28927since one effect of this pragma is to require the presence of a package body. 28928 28929@item 28930@emph{Numeric_Error is the same exception as Constraint_Error} 28931 28932In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. 28933This means that it is illegal to have separate exception handlers for 28934the two exceptions. The fix is simply to remove the handler for the 28935@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 28936@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). 28937 28938@item 28939@emph{Indefinite subtypes in generics} 28940 28941In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) 28942as the actual for a generic formal private type, but then the instantiation 28943would be illegal if there were any instances of declarations of variables 28944of this type in the generic body. In Ada 95, to avoid this clear violation 28945of the methodological principle known as the 'contract model', 28946the generic declaration explicitly indicates whether 28947or not such instantiations are permitted. If a generic formal parameter 28948has explicit unknown discriminants, indicated by using @code{(<>)} after the 28949subtype name, then it can be instantiated with indefinite types, but no 28950stand-alone variables can be declared of this type. Any attempt to declare 28951such a variable will result in an illegality at the time the generic is 28952declared. If the @code{(<>)} notation is not used, then it is illegal 28953to instantiate the generic with an indefinite type. 28954This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 28955It will show up as a compile time error, and 28956the fix is usually simply to add the @code{(<>)} to the generic declaration. 28957@end itemize 28958 28959@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 28960@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{442}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{443} 28961@subsection More deterministic semantics 28962 28963 28964 28965@itemize * 28966 28967@item 28968@emph{Conversions} 28969 28970Conversions from real types to integer types round away from 0. In Ada 83 28971the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 28972implementation freedom was intended to support unbiased rounding in 28973statistical applications, but in practice it interfered with portability. 28974In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 28975is required. Numeric code may be affected by this change in semantics. 28976Note, though, that this issue is no worse than already existed in Ada 83 28977when porting code from one vendor to another. 28978 28979@item 28980@emph{Tasking} 28981 28982The Real-Time Annex introduces a set of policies that define the behavior of 28983features that were implementation dependent in Ada 83, such as the order in 28984which open select branches are executed. 28985@end itemize 28986 28987@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 28988@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{445} 28989@subsection Changed semantics 28990 28991 28992The worst kind of incompatibility is one where a program that is legal in 28993Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 28994possible in Ada 83. Fortunately this is extremely rare, but the one 28995situation that you should be alert to is the change in the predefined type 28996@code{Character} from 7-bit ASCII to 8-bit Latin-1. 28997 28998@quotation 28999 29000@geindex Latin-1 29001@end quotation 29002 29003 29004@itemize * 29005 29006@item 29007@emph{Range of type `@w{`}Character`@w{`}} 29008 29009The range of @code{Standard.Character} is now the full 256 characters 29010of Latin-1, whereas in most Ada 83 implementations it was restricted 29011to 128 characters. Although some of the effects of 29012this change will be manifest in compile-time rejection of legal 29013Ada 83 programs it is possible for a working Ada 83 program to have 29014a different effect in Ada 95, one that was not permitted in Ada 83. 29015As an example, the expression 29016@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now 29017delivers @code{255} as its value. 29018In general, you should look at the logic of any 29019character-processing Ada 83 program and see whether it needs to be adapted 29020to work correctly with Latin-1. Note that the predefined Ada 95 API has a 29021character handling package that may be relevant if code needs to be adapted 29022to account for the additional Latin-1 elements. 29023The desirable fix is to 29024modify the program to accommodate the full character set, but in some cases 29025it may be convenient to define a subtype or derived type of Character that 29026covers only the restricted range. 29027@end itemize 29028 29029@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 29030@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{447} 29031@subsection Other language compatibility issues 29032 29033 29034 29035@itemize * 29036 29037@item 29038@emph{-gnat83} switch 29039 29040All implementations of GNAT provide a switch that causes GNAT to operate 29041in Ada 83 mode. In this mode, some but not all compatibility problems 29042of the type described above are handled automatically. For example, the 29043new reserved words introduced in Ada 95 and Ada 2005 are treated simply 29044as identifiers as in Ada 83. However, 29045in practice, it is usually advisable to make the necessary modifications 29046to the program to remove the need for using this switch. 29047See the @code{Compiling Different Versions of Ada} section in 29048the @cite{GNAT User's Guide}. 29049 29050@item 29051Support for removed Ada 83 pragmas and attributes 29052 29053A number of pragmas and attributes from Ada 83 were removed from Ada 95, 29054generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 29055compilers are allowed, but not required, to implement these missing 29056elements. In contrast with some other compilers, GNAT implements all 29057such pragmas and attributes, eliminating this compatibility concern. These 29058include @code{pragma Interface} and the floating point type attributes 29059(@code{Emax}, @code{Mantissa}, etc.), among other items. 29060@end itemize 29061 29062@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 29063@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{449} 29064@section Compatibility between Ada 95 and Ada 2005 29065 29066 29067@geindex Compatibility between Ada 95 and Ada 2005 29068 29069Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 29070a number of incompatibilities. Several are enumerated below; 29071for a complete description please see the 29072@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 29073@cite{Rationale for Ada 2005}. 29074 29075 29076@itemize * 29077 29078@item 29079@emph{New reserved words.} 29080 29081The words @code{interface}, @code{overriding} and @code{synchronized} are 29082reserved in Ada 2005. 29083A pre-Ada 2005 program that uses any of these as an identifier will be 29084illegal. 29085 29086@item 29087@emph{New declarations in predefined packages.} 29088 29089A number of packages in the predefined environment contain new declarations: 29090@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, 29091@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, 29092@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, 29093@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, 29094@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. 29095If an Ada 95 program does a @code{with} and @code{use} of any of these 29096packages, the new declarations may cause name clashes. 29097 29098@item 29099@emph{Access parameters.} 29100 29101A nondispatching subprogram with an access parameter cannot be renamed 29102as a dispatching operation. This was permitted in Ada 95. 29103 29104@item 29105@emph{Access types, discriminants, and constraints.} 29106 29107Rule changes in this area have led to some incompatibilities; for example, 29108constrained subtypes of some access types are not permitted in Ada 2005. 29109 29110@item 29111@emph{Aggregates for limited types.} 29112 29113The allowance of aggregates for limited types in Ada 2005 raises the 29114possibility of ambiguities in legal Ada 95 programs, since additional types 29115now need to be considered in expression resolution. 29116 29117@item 29118@emph{Fixed-point multiplication and division.} 29119 29120Certain expressions involving '*' or '/' for a fixed-point type, which 29121were legal in Ada 95 and invoked the predefined versions of these operations, 29122are now ambiguous. 29123The ambiguity may be resolved either by applying a type conversion to the 29124expression, or by explicitly invoking the operation from package 29125@code{Standard}. 29126 29127@item 29128@emph{Return-by-reference types.} 29129 29130The Ada 95 return-by-reference mechanism has been removed. Instead, the user 29131can declare a function returning a value from an anonymous access type. 29132@end itemize 29133 29134@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 29135@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{44b} 29136@section Implementation-dependent characteristics 29137 29138 29139Although the Ada language defines the semantics of each construct as 29140precisely as practical, in some situations (for example for reasons of 29141efficiency, or where the effect is heavily dependent on the host or target 29142platform) the implementation is allowed some freedom. In porting Ada 83 29143code to GNAT, you need to be aware of whether / how the existing code 29144exercised such implementation dependencies. Such characteristics fall into 29145several categories, and GNAT offers specific support in assisting the 29146transition from certain Ada 83 compilers. 29147 29148@menu 29149* Implementation-defined pragmas:: 29150* Implementation-defined attributes:: 29151* Libraries:: 29152* Elaboration order:: 29153* Target-specific aspects:: 29154 29155@end menu 29156 29157@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 29158@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{44d} 29159@subsection Implementation-defined pragmas 29160 29161 29162Ada compilers are allowed to supplement the language-defined pragmas, and 29163these are a potential source of non-portability. All GNAT-defined pragmas 29164are described in @ref{7,,Implementation Defined Pragmas}, 29165and these include several that are specifically 29166intended to correspond to other vendors' Ada 83 pragmas. 29167For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. 29168For compatibility with HP Ada 83, GNAT supplies the pragmas 29169@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, 29170@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, 29171and @code{Volatile}. 29172Other relevant pragmas include @code{External} and @code{Link_With}. 29173Some vendor-specific 29174Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are 29175recognized, thus 29176avoiding compiler rejection of units that contain such pragmas; they are not 29177relevant in a GNAT context and hence are not otherwise implemented. 29178 29179@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 29180@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{44f} 29181@subsection Implementation-defined attributes 29182 29183 29184Analogous to pragmas, the set of attributes may be extended by an 29185implementation. All GNAT-defined attributes are described in 29186@ref{8,,Implementation Defined Attributes}, 29187and these include several that are specifically intended 29188to correspond to other vendors' Ada 83 attributes. For migrating from VADS, 29189the attribute @code{VADS_Size} may be useful. For compatibility with HP 29190Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and 29191@code{Type_Class}. 29192 29193@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 29194@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{451} 29195@subsection Libraries 29196 29197 29198Vendors may supply libraries to supplement the standard Ada API. If Ada 83 29199code uses vendor-specific libraries then there are several ways to manage 29200this in Ada 95 and later versions of the standard: 29201 29202 29203@itemize * 29204 29205@item 29206If the source code for the libraries (specs and bodies) are 29207available, then the libraries can be migrated in the same way as the 29208application. 29209 29210@item 29211If the source code for the specs but not the bodies are 29212available, then you can reimplement the bodies. 29213 29214@item 29215Some features introduced by Ada 95 obviate the need for library support. For 29216example most Ada 83 vendors supplied a package for unsigned integers. The 29217Ada 95 modular type feature is the preferred way to handle this need, so 29218instead of migrating or reimplementing the unsigned integer package it may 29219be preferable to retrofit the application using modular types. 29220@end itemize 29221 29222@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 29223@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{453} 29224@subsection Elaboration order 29225 29226 29227The implementation can choose any elaboration order consistent with the unit 29228dependency relationship. This freedom means that some orders can result in 29229Program_Error being raised due to an 'Access Before Elaboration': an attempt 29230to invoke a subprogram before its body has been elaborated, or to instantiate 29231a generic before the generic body has been elaborated. By default GNAT 29232attempts to choose a safe order (one that will not encounter access before 29233elaboration problems) by implicitly inserting @code{Elaborate} or 29234@code{Elaborate_All} pragmas where 29235needed. However, this can lead to the creation of elaboration circularities 29236and a resulting rejection of the program by gnatbind. This issue is 29237thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix 29238in the @cite{GNAT User's Guide}. 29239In brief, there are several 29240ways to deal with this situation: 29241 29242 29243@itemize * 29244 29245@item 29246Modify the program to eliminate the circularities, e.g., by moving 29247elaboration-time code into explicitly-invoked procedures 29248 29249@item 29250Constrain the elaboration order by including explicit @code{Elaborate_Body} or 29251@code{Elaborate} pragmas, and then inhibit the generation of implicit 29252@code{Elaborate_All} 29253pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 29254(by selectively suppressing elaboration checks via pragma 29255@code{Suppress(Elaboration_Check)} when it is safe to do so). 29256@end itemize 29257 29258@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 29259@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{455} 29260@subsection Target-specific aspects 29261 29262 29263Low-level applications need to deal with machine addresses, data 29264representations, interfacing with assembler code, and similar issues. If 29265such an Ada 83 application is being ported to different target hardware (for 29266example where the byte endianness has changed) then you will need to 29267carefully examine the program logic; the porting effort will heavily depend 29268on the robustness of the original design. Moreover, Ada 95 (and thus 29269Ada 2005 and Ada 2012) are sometimes 29270incompatible with typical Ada 83 compiler practices regarding implicit 29271packing, the meaning of the Size attribute, and the size of access values. 29272GNAT's approach to these issues is described in @ref{456,,Representation Clauses}. 29273 29274@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 29275@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{457}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{458} 29276@section Compatibility with Other Ada Systems 29277 29278 29279If programs avoid the use of implementation dependent and 29280implementation defined features, as documented in the 29281@cite{Ada Reference Manual}, there should be a high degree of portability between 29282GNAT and other Ada systems. The following are specific items which 29283have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 29284compilers, but do not affect porting code to GNAT. 29285(As of January 2007, GNAT is the only compiler available for Ada 2005; 29286the following issues may or may not arise for Ada 2005 programs 29287when other compilers appear.) 29288 29289 29290@itemize * 29291 29292@item 29293@emph{Ada 83 Pragmas and Attributes} 29294 29295Ada 95 compilers are allowed, but not required, to implement the missing 29296Ada 83 pragmas and attributes that are no longer defined in Ada 95. 29297GNAT implements all such pragmas and attributes, eliminating this as 29298a compatibility concern, but some other Ada 95 compilers reject these 29299pragmas and attributes. 29300 29301@item 29302@emph{Specialized Needs Annexes} 29303 29304GNAT implements the full set of special needs annexes. At the 29305current time, it is the only Ada 95 compiler to do so. This means that 29306programs making use of these features may not be portable to other Ada 2930795 compilation systems. 29308 29309@item 29310@emph{Representation Clauses} 29311 29312Some other Ada 95 compilers implement only the minimal set of 29313representation clauses required by the Ada 95 reference manual. GNAT goes 29314far beyond this minimal set, as described in the next section. 29315@end itemize 29316 29317@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 29318@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{459} 29319@section Representation Clauses 29320 29321 29322The Ada 83 reference manual was quite vague in describing both the minimal 29323required implementation of representation clauses, and also their precise 29324effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 29325minimal set of capabilities required is still quite limited. 29326 29327GNAT implements the full required set of capabilities in 29328Ada 95 and Ada 2005, but also goes much further, and in particular 29329an effort has been made to be compatible with existing Ada 83 usage to the 29330greatest extent possible. 29331 29332A few cases exist in which Ada 83 compiler behavior is incompatible with 29333the requirements in Ada 95 (and thus also Ada 2005). These are instances of 29334intentional or accidental dependence on specific implementation dependent 29335characteristics of these Ada 83 compilers. The following is a list of 29336the cases most likely to arise in existing Ada 83 code. 29337 29338 29339@itemize * 29340 29341@item 29342@emph{Implicit Packing} 29343 29344Some Ada 83 compilers allowed a Size specification to cause implicit 29345packing of an array or record. This could cause expensive implicit 29346conversions for change of representation in the presence of derived 29347types, and the Ada design intends to avoid this possibility. 29348Subsequent AI's were issued to make it clear that such implicit 29349change of representation in response to a Size clause is inadvisable, 29350and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 29351Reference Manuals as implementation advice that is followed by GNAT. 29352The problem will show up as an error 29353message rejecting the size clause. The fix is simply to provide 29354the explicit pragma @code{Pack}, or for more fine tuned control, provide 29355a Component_Size clause. 29356 29357@item 29358@emph{Meaning of Size Attribute} 29359 29360The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 29361the minimal number of bits required to hold values of the type. For example, 29362on a 32-bit machine, the size of @code{Natural} will typically be 31 and not 2936332 (since no sign bit is required). Some Ada 83 compilers gave 31, and 29364some 32 in this situation. This problem will usually show up as a compile 29365time error, but not always. It is a good idea to check all uses of the 29366'Size attribute when porting Ada 83 code. The GNAT specific attribute 29367Object_Size can provide a useful way of duplicating the behavior of 29368some Ada 83 compiler systems. 29369 29370@item 29371@emph{Size of Access Types} 29372 29373A common assumption in Ada 83 code is that an access type is in fact a pointer, 29374and that therefore it will be the same size as a System.Address value. This 29375assumption is true for GNAT in most cases with one exception. For the case of 29376a pointer to an unconstrained array type (where the bounds may vary from one 29377value of the access type to another), the default is to use a 'fat pointer', 29378which is represented as two separate pointers, one to the bounds, and one to 29379the array. This representation has a number of advantages, including improved 29380efficiency. However, it may cause some difficulties in porting existing Ada 83 29381code which makes the assumption that, for example, pointers fit in 32 bits on 29382a machine with 32-bit addressing. 29383 29384To get around this problem, GNAT also permits the use of 'thin pointers' for 29385access types in this case (where the designated type is an unconstrained array 29386type). These thin pointers are indeed the same size as a System.Address value. 29387To specify a thin pointer, use a size clause for the type, for example: 29388 29389@example 29390type X is access all String; 29391for X'Size use Standard'Address_Size; 29392@end example 29393 29394which will cause the type X to be represented using a single pointer. 29395When using this representation, the bounds are right behind the array. 29396This representation is slightly less efficient, and does not allow quite 29397such flexibility in the use of foreign pointers or in using the 29398Unrestricted_Access attribute to create pointers to non-aliased objects. 29399But for any standard portable use of the access type it will work in 29400a functionally correct manner and allow porting of existing code. 29401Note that another way of forcing a thin pointer representation 29402is to use a component size clause for the element size in an array, 29403or a record representation clause for an access field in a record. 29404 29405See the documentation of Unrestricted_Access in the GNAT RM for a 29406full discussion of possible problems using this attribute in conjunction 29407with thin pointers. 29408@end itemize 29409 29410@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 29411@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{45b} 29412@section Compatibility with HP Ada 83 29413 29414 29415All the HP Ada 83 pragmas and attributes are recognized, although only a subset 29416of them can sensibly be implemented. The description of pragmas in 29417@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 29418applicable to GNAT. 29419 29420 29421@itemize * 29422 29423@item 29424@emph{Default floating-point representation} 29425 29426In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 29427it is VMS format. 29428 29429@item 29430@emph{System} 29431 29432the package System in GNAT exactly corresponds to the definition in the 29433Ada 95 reference manual, which means that it excludes many of the 29434HP Ada 83 extensions. However, a separate package Aux_DEC is provided 29435that contains the additional definitions, and a special pragma, 29436Extend_System allows this package to be treated transparently as an 29437extension of package System. 29438@end itemize 29439 29440@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 29441@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{45c}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{45d} 29442@chapter GNU Free Documentation License 29443 29444 29445Version 1.3, 3 November 2008 29446 29447Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 29448@indicateurl{http://fsf.org/} 29449 29450Everyone is permitted to copy and distribute verbatim copies of this 29451license document, but changing it is not allowed. 29452 29453@strong{Preamble} 29454 29455The purpose of this License is to make a manual, textbook, or other 29456functional and useful document "free" in the sense of freedom: to 29457assure everyone the effective freedom to copy and redistribute it, 29458with or without modifying it, either commercially or noncommercially. 29459Secondarily, this License preserves for the author and publisher a way 29460to get credit for their work, while not being considered responsible 29461for modifications made by others. 29462 29463This License is a kind of "copyleft", which means that derivative 29464works of the document must themselves be free in the same sense. It 29465complements the GNU General Public License, which is a copyleft 29466license designed for free software. 29467 29468We have designed this License in order to use it for manuals for free 29469software, because free software needs free documentation: a free 29470program should come with manuals providing the same freedoms that the 29471software does. But this License is not limited to software manuals; 29472it can be used for any textual work, regardless of subject matter or 29473whether it is published as a printed book. We recommend this License 29474principally for works whose purpose is instruction or reference. 29475 29476@strong{1. APPLICABILITY AND DEFINITIONS} 29477 29478This License applies to any manual or other work, in any medium, that 29479contains a notice placed by the copyright holder saying it can be 29480distributed under the terms of this License. Such a notice grants a 29481world-wide, royalty-free license, unlimited in duration, to use that 29482work under the conditions stated herein. The @strong{Document}, below, 29483refers to any such manual or work. Any member of the public is a 29484licensee, and is addressed as "@strong{you}". You accept the license if you 29485copy, modify or distribute the work in a way requiring permission 29486under copyright law. 29487 29488A "@strong{Modified Version}" of the Document means any work containing the 29489Document or a portion of it, either copied verbatim, or with 29490modifications and/or translated into another language. 29491 29492A "@strong{Secondary Section}" is a named appendix or a front-matter section of 29493the Document that deals exclusively with the relationship of the 29494publishers or authors of the Document to the Document's overall subject 29495(or to related matters) and contains nothing that could fall directly 29496within that overall subject. (Thus, if the Document is in part a 29497textbook of mathematics, a Secondary Section may not explain any 29498mathematics.) The relationship could be a matter of historical 29499connection with the subject or with related matters, or of legal, 29500commercial, philosophical, ethical or political position regarding 29501them. 29502 29503The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 29504are designated, as being those of Invariant Sections, in the notice 29505that says that the Document is released under this License. If a 29506section does not fit the above definition of Secondary then it is not 29507allowed to be designated as Invariant. The Document may contain zero 29508Invariant Sections. If the Document does not identify any Invariant 29509Sections then there are none. 29510 29511The "@strong{Cover Texts}" are certain short passages of text that are listed, 29512as Front-Cover Texts or Back-Cover Texts, in the notice that says that 29513the Document is released under this License. A Front-Cover Text may 29514be at most 5 words, and a Back-Cover Text may be at most 25 words. 29515 29516A "@strong{Transparent}" copy of the Document means a machine-readable copy, 29517represented in a format whose specification is available to the 29518general public, that is suitable for revising the document 29519straightforwardly with generic text editors or (for images composed of 29520pixels) generic paint programs or (for drawings) some widely available 29521drawing editor, and that is suitable for input to text formatters or 29522for automatic translation to a variety of formats suitable for input 29523to text formatters. A copy made in an otherwise Transparent file 29524format whose markup, or absence of markup, has been arranged to thwart 29525or discourage subsequent modification by readers is not Transparent. 29526An image format is not Transparent if used for any substantial amount 29527of text. A copy that is not "Transparent" is called @strong{Opaque}. 29528 29529Examples of suitable formats for Transparent copies include plain 29530ASCII without markup, Texinfo input format, LaTeX input format, SGML 29531or XML using a publicly available DTD, and standard-conforming simple 29532HTML, PostScript or PDF designed for human modification. Examples of 29533transparent image formats include PNG, XCF and JPG. Opaque formats 29534include proprietary formats that can be read and edited only by 29535proprietary word processors, SGML or XML for which the DTD and/or 29536processing tools are not generally available, and the 29537machine-generated HTML, PostScript or PDF produced by some word 29538processors for output purposes only. 29539 29540The "@strong{Title Page}" means, for a printed book, the title page itself, 29541plus such following pages as are needed to hold, legibly, the material 29542this License requires to appear in the title page. For works in 29543formats which do not have any title page as such, "Title Page" means 29544the text near the most prominent appearance of the work's title, 29545preceding the beginning of the body of the text. 29546 29547The "@strong{publisher}" means any person or entity that distributes 29548copies of the Document to the public. 29549 29550A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 29551title either is precisely XYZ or contains XYZ in parentheses following 29552text that translates XYZ in another language. (Here XYZ stands for a 29553specific section name mentioned below, such as "@strong{Acknowledgements}", 29554"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 29555To "@strong{Preserve the Title}" 29556of such a section when you modify the Document means that it remains a 29557section "Entitled XYZ" according to this definition. 29558 29559The Document may include Warranty Disclaimers next to the notice which 29560states that this License applies to the Document. These Warranty 29561Disclaimers are considered to be included by reference in this 29562License, but only as regards disclaiming warranties: any other 29563implication that these Warranty Disclaimers may have is void and has 29564no effect on the meaning of this License. 29565 29566@strong{2. VERBATIM COPYING} 29567 29568You may copy and distribute the Document in any medium, either 29569commercially or noncommercially, provided that this License, the 29570copyright notices, and the license notice saying this License applies 29571to the Document are reproduced in all copies, and that you add no other 29572conditions whatsoever to those of this License. You may not use 29573technical measures to obstruct or control the reading or further 29574copying of the copies you make or distribute. However, you may accept 29575compensation in exchange for copies. If you distribute a large enough 29576number of copies you must also follow the conditions in section 3. 29577 29578You may also lend copies, under the same conditions stated above, and 29579you may publicly display copies. 29580 29581@strong{3. COPYING IN QUANTITY} 29582 29583If you publish printed copies (or copies in media that commonly have 29584printed covers) of the Document, numbering more than 100, and the 29585Document's license notice requires Cover Texts, you must enclose the 29586copies in covers that carry, clearly and legibly, all these Cover 29587Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 29588the back cover. Both covers must also clearly and legibly identify 29589you as the publisher of these copies. The front cover must present 29590the full title with all words of the title equally prominent and 29591visible. You may add other material on the covers in addition. 29592Copying with changes limited to the covers, as long as they preserve 29593the title of the Document and satisfy these conditions, can be treated 29594as verbatim copying in other respects. 29595 29596If the required texts for either cover are too voluminous to fit 29597legibly, you should put the first ones listed (as many as fit 29598reasonably) on the actual cover, and continue the rest onto adjacent 29599pages. 29600 29601If you publish or distribute Opaque copies of the Document numbering 29602more than 100, you must either include a machine-readable Transparent 29603copy along with each Opaque copy, or state in or with each Opaque copy 29604a computer-network location from which the general network-using 29605public has access to download using public-standard network protocols 29606a complete Transparent copy of the Document, free of added material. 29607If you use the latter option, you must take reasonably prudent steps, 29608when you begin distribution of Opaque copies in quantity, to ensure 29609that this Transparent copy will remain thus accessible at the stated 29610location until at least one year after the last time you distribute an 29611Opaque copy (directly or through your agents or retailers) of that 29612edition to the public. 29613 29614It is requested, but not required, that you contact the authors of the 29615Document well before redistributing any large number of copies, to give 29616them a chance to provide you with an updated version of the Document. 29617 29618@strong{4. MODIFICATIONS} 29619 29620You may copy and distribute a Modified Version of the Document under 29621the conditions of sections 2 and 3 above, provided that you release 29622the Modified Version under precisely this License, with the Modified 29623Version filling the role of the Document, thus licensing distribution 29624and modification of the Modified Version to whoever possesses a copy 29625of it. In addition, you must do these things in the Modified Version: 29626 29627 29628@enumerate A 29629 29630@item 29631Use in the Title Page (and on the covers, if any) a title distinct 29632from that of the Document, and from those of previous versions 29633(which should, if there were any, be listed in the History section 29634of the Document). You may use the same title as a previous version 29635if the original publisher of that version gives permission. 29636 29637@item 29638List on the Title Page, as authors, one or more persons or entities 29639responsible for authorship of the modifications in the Modified 29640Version, together with at least five of the principal authors of the 29641Document (all of its principal authors, if it has fewer than five), 29642unless they release you from this requirement. 29643 29644@item 29645State on the Title page the name of the publisher of the 29646Modified Version, as the publisher. 29647 29648@item 29649Preserve all the copyright notices of the Document. 29650 29651@item 29652Add an appropriate copyright notice for your modifications 29653adjacent to the other copyright notices. 29654 29655@item 29656Include, immediately after the copyright notices, a license notice 29657giving the public permission to use the Modified Version under the 29658terms of this License, in the form shown in the Addendum below. 29659 29660@item 29661Preserve in that license notice the full lists of Invariant Sections 29662and required Cover Texts given in the Document's license notice. 29663 29664@item 29665Include an unaltered copy of this License. 29666 29667@item 29668Preserve the section Entitled "History", Preserve its Title, and add 29669to it an item stating at least the title, year, new authors, and 29670publisher of the Modified Version as given on the Title Page. If 29671there is no section Entitled "History" in the Document, create one 29672stating the title, year, authors, and publisher of the Document as 29673given on its Title Page, then add an item describing the Modified 29674Version as stated in the previous sentence. 29675 29676@item 29677Preserve the network location, if any, given in the Document for 29678public access to a Transparent copy of the Document, and likewise 29679the network locations given in the Document for previous versions 29680it was based on. These may be placed in the "History" section. 29681You may omit a network location for a work that was published at 29682least four years before the Document itself, or if the original 29683publisher of the version it refers to gives permission. 29684 29685@item 29686For any section Entitled "Acknowledgements" or "Dedications", 29687Preserve the Title of the section, and preserve in the section all 29688the substance and tone of each of the contributor acknowledgements 29689and/or dedications given therein. 29690 29691@item 29692Preserve all the Invariant Sections of the Document, 29693unaltered in their text and in their titles. Section numbers 29694or the equivalent are not considered part of the section titles. 29695 29696@item 29697Delete any section Entitled "Endorsements". Such a section 29698may not be included in the Modified Version. 29699 29700@item 29701Do not retitle any existing section to be Entitled "Endorsements" 29702or to conflict in title with any Invariant Section. 29703 29704@item 29705Preserve any Warranty Disclaimers. 29706@end enumerate 29707 29708If the Modified Version includes new front-matter sections or 29709appendices that qualify as Secondary Sections and contain no material 29710copied from the Document, you may at your option designate some or all 29711of these sections as invariant. To do this, add their titles to the 29712list of Invariant Sections in the Modified Version's license notice. 29713These titles must be distinct from any other section titles. 29714 29715You may add a section Entitled "Endorsements", provided it contains 29716nothing but endorsements of your Modified Version by various 29717parties---for example, statements of peer review or that the text has 29718been approved by an organization as the authoritative definition of a 29719standard. 29720 29721You may add a passage of up to five words as a Front-Cover Text, and a 29722passage of up to 25 words as a Back-Cover Text, to the end of the list 29723of Cover Texts in the Modified Version. Only one passage of 29724Front-Cover Text and one of Back-Cover Text may be added by (or 29725through arrangements made by) any one entity. If the Document already 29726includes a cover text for the same cover, previously added by you or 29727by arrangement made by the same entity you are acting on behalf of, 29728you may not add another; but you may replace the old one, on explicit 29729permission from the previous publisher that added the old one. 29730 29731The author(s) and publisher(s) of the Document do not by this License 29732give permission to use their names for publicity for or to assert or 29733imply endorsement of any Modified Version. 29734 29735@strong{5. COMBINING DOCUMENTS} 29736 29737You may combine the Document with other documents released under this 29738License, under the terms defined in section 4 above for modified 29739versions, provided that you include in the combination all of the 29740Invariant Sections of all of the original documents, unmodified, and 29741list them all as Invariant Sections of your combined work in its 29742license notice, and that you preserve all their Warranty Disclaimers. 29743 29744The combined work need only contain one copy of this License, and 29745multiple identical Invariant Sections may be replaced with a single 29746copy. If there are multiple Invariant Sections with the same name but 29747different contents, make the title of each such section unique by 29748adding at the end of it, in parentheses, the name of the original 29749author or publisher of that section if known, or else a unique number. 29750Make the same adjustment to the section titles in the list of 29751Invariant Sections in the license notice of the combined work. 29752 29753In the combination, you must combine any sections Entitled "History" 29754in the various original documents, forming one section Entitled 29755"History"; likewise combine any sections Entitled "Acknowledgements", 29756and any sections Entitled "Dedications". You must delete all sections 29757Entitled "Endorsements". 29758 29759@strong{6. COLLECTIONS OF DOCUMENTS} 29760 29761You may make a collection consisting of the Document and other documents 29762released under this License, and replace the individual copies of this 29763License in the various documents with a single copy that is included in 29764the collection, provided that you follow the rules of this License for 29765verbatim copying of each of the documents in all other respects. 29766 29767You may extract a single document from such a collection, and distribute 29768it individually under this License, provided you insert a copy of this 29769License into the extracted document, and follow this License in all 29770other respects regarding verbatim copying of that document. 29771 29772@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29773 29774A compilation of the Document or its derivatives with other separate 29775and independent documents or works, in or on a volume of a storage or 29776distribution medium, is called an "aggregate" if the copyright 29777resulting from the compilation is not used to limit the legal rights 29778of the compilation's users beyond what the individual works permit. 29779When the Document is included in an aggregate, this License does not 29780apply to the other works in the aggregate which are not themselves 29781derivative works of the Document. 29782 29783If the Cover Text requirement of section 3 is applicable to these 29784copies of the Document, then if the Document is less than one half of 29785the entire aggregate, the Document's Cover Texts may be placed on 29786covers that bracket the Document within the aggregate, or the 29787electronic equivalent of covers if the Document is in electronic form. 29788Otherwise they must appear on printed covers that bracket the whole 29789aggregate. 29790 29791@strong{8. TRANSLATION} 29792 29793Translation is considered a kind of modification, so you may 29794distribute translations of the Document under the terms of section 4. 29795Replacing Invariant Sections with translations requires special 29796permission from their copyright holders, but you may include 29797translations of some or all Invariant Sections in addition to the 29798original versions of these Invariant Sections. You may include a 29799translation of this License, and all the license notices in the 29800Document, and any Warranty Disclaimers, provided that you also include 29801the original English version of this License and the original versions 29802of those notices and disclaimers. In case of a disagreement between 29803the translation and the original version of this License or a notice 29804or disclaimer, the original version will prevail. 29805 29806If a section in the Document is Entitled "Acknowledgements", 29807"Dedications", or "History", the requirement (section 4) to Preserve 29808its Title (section 1) will typically require changing the actual 29809title. 29810 29811@strong{9. TERMINATION} 29812 29813You may not copy, modify, sublicense, or distribute the Document 29814except as expressly provided under this License. Any attempt 29815otherwise to copy, modify, sublicense, or distribute it is void, and 29816will automatically terminate your rights under this License. 29817 29818However, if you cease all violation of this License, then your license 29819from a particular copyright holder is reinstated (a) provisionally, 29820unless and until the copyright holder explicitly and finally 29821terminates your license, and (b) permanently, if the copyright holder 29822fails to notify you of the violation by some reasonable means prior to 2982360 days after the cessation. 29824 29825Moreover, your license from a particular copyright holder is 29826reinstated permanently if the copyright holder notifies you of the 29827violation by some reasonable means, this is the first time you have 29828received notice of violation of this License (for any work) from that 29829copyright holder, and you cure the violation prior to 30 days after 29830your receipt of the notice. 29831 29832Termination of your rights under this section does not terminate the 29833licenses of parties who have received copies or rights from you under 29834this License. If your rights have been terminated and not permanently 29835reinstated, receipt of a copy of some or all of the same material does 29836not give you any rights to use it. 29837 29838@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29839 29840The Free Software Foundation may publish new, revised versions 29841of the GNU Free Documentation License from time to time. Such new 29842versions will be similar in spirit to the present version, but may 29843differ in detail to address new problems or concerns. See 29844@indicateurl{http://www.gnu.org/copyleft/}. 29845 29846Each version of the License is given a distinguishing version number. 29847If the Document specifies that a particular numbered version of this 29848License "or any later version" applies to it, you have the option of 29849following the terms and conditions either of that specified version or 29850of any later version that has been published (not as a draft) by the 29851Free Software Foundation. If the Document does not specify a version 29852number of this License, you may choose any version ever published (not 29853as a draft) by the Free Software Foundation. If the Document 29854specifies that a proxy can decide which future versions of this 29855License can be used, that proxy's public statement of acceptance of a 29856version permanently authorizes you to choose that version for the 29857Document. 29858 29859@strong{11. RELICENSING} 29860 29861"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 29862World Wide Web server that publishes copyrightable works and also 29863provides prominent facilities for anybody to edit those works. A 29864public wiki that anybody can edit is an example of such a server. A 29865"Massive Multiauthor Collaboration" (or "MMC") contained in the 29866site means any set of copyrightable works thus published on the MMC 29867site. 29868 29869"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 29870license published by Creative Commons Corporation, a not-for-profit 29871corporation with a principal place of business in San Francisco, 29872California, as well as future copyleft versions of that license 29873published by that same organization. 29874 29875"Incorporate" means to publish or republish a Document, in whole or 29876in part, as part of another Document. 29877 29878An MMC is "eligible for relicensing" if it is licensed under this 29879License, and if all works that were first published under this License 29880somewhere other than this MMC, and subsequently incorporated in whole 29881or in part into the MMC, (1) had no cover texts or invariant sections, 29882and (2) were thus incorporated prior to November 1, 2008. 29883 29884The operator of an MMC Site may republish an MMC contained in the site 29885under CC-BY-SA on the same site at any time before August 1, 2009, 29886provided the MMC is eligible for relicensing. 29887 29888@strong{ADDENDUM: How to use this License for your documents} 29889 29890To use this License in a document you have written, include a copy of 29891the License in the document and put the following copyright and 29892license notices just after the title page: 29893 29894@quotation 29895 29896Copyright © YEAR YOUR NAME. 29897Permission is granted to copy, distribute and/or modify this document 29898under the terms of the GNU Free Documentation License, Version 1.3 29899or any later version published by the Free Software Foundation; 29900with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 29901A copy of the license is included in the section entitled "GNU 29902Free Documentation License". 29903@end quotation 29904 29905If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 29906replace the "with ... Texts." line with this: 29907 29908@quotation 29909 29910with the Invariant Sections being LIST THEIR TITLES, with the 29911Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 29912@end quotation 29913 29914If you have Invariant Sections without Cover Texts, or some other 29915combination of the three, merge those two alternatives to suit the 29916situation. 29917 29918If your document contains nontrivial examples of program code, we 29919recommend releasing these examples in parallel under your choice of 29920free software license, such as the GNU General Public License, 29921to permit their use in free software. 29922 29923@node Index,,GNU Free Documentation License,Top 29924@unnumbered Index 29925 29926 29927@printindex ge 29928 29929 29930@c %**end of body 29931@bye 29932