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.3b2.@* 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 , November 18, 2015 25 26AdaCore 27 28Copyright @copyright{} 2008-2016, 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 Ada_83:: 101* Pragma Ada_95:: 102* Pragma Ada_05:: 103* Pragma Ada_2005:: 104* Pragma Ada_12:: 105* Pragma Ada_2012:: 106* Pragma Allow_Integer_Address:: 107* Pragma Annotate:: 108* Pragma Assert:: 109* Pragma Assert_And_Cut:: 110* Pragma Assertion_Policy:: 111* Pragma Assume:: 112* Pragma Assume_No_Invalid_Values:: 113* Pragma Async_Readers:: 114* Pragma Async_Writers:: 115* Pragma Attribute_Definition:: 116* Pragma C_Pass_By_Copy:: 117* Pragma Check:: 118* Pragma Check_Float_Overflow:: 119* Pragma Check_Name:: 120* Pragma Check_Policy:: 121* Pragma Comment:: 122* Pragma Common_Object:: 123* Pragma Compile_Time_Error:: 124* Pragma Compile_Time_Warning:: 125* Pragma Compiler_Unit:: 126* Pragma Compiler_Unit_Warning:: 127* Pragma Complete_Representation:: 128* Pragma Complex_Representation:: 129* Pragma Component_Alignment:: 130* Pragma Constant_After_Elaboration:: 131* Pragma Contract_Cases:: 132* Pragma Convention_Identifier:: 133* Pragma CPP_Class:: 134* Pragma CPP_Constructor:: 135* Pragma CPP_Virtual:: 136* Pragma CPP_Vtable:: 137* Pragma CPU:: 138* Pragma Default_Initial_Condition:: 139* Pragma Debug:: 140* Pragma Debug_Policy:: 141* Pragma Default_Scalar_Storage_Order:: 142* Pragma Default_Storage_Pool:: 143* Pragma Depends:: 144* Pragma Detect_Blocking:: 145* Pragma Disable_Atomic_Synchronization:: 146* Pragma Dispatching_Domain:: 147* Pragma Effective_Reads:: 148* Pragma Effective_Writes:: 149* Pragma Elaboration_Checks:: 150* Pragma Eliminate:: 151* Pragma Enable_Atomic_Synchronization:: 152* Pragma Export_Function:: 153* Pragma Export_Object:: 154* Pragma Export_Procedure:: 155* Pragma Export_Value:: 156* Pragma Export_Valued_Procedure:: 157* Pragma Extend_System:: 158* Pragma Extensions_Allowed:: 159* Pragma Extensions_Visible:: 160* Pragma External:: 161* Pragma External_Name_Casing:: 162* Pragma Fast_Math:: 163* Pragma Favor_Top_Level:: 164* Pragma Finalize_Storage_Only:: 165* Pragma Float_Representation:: 166* Pragma Ghost:: 167* Pragma Global:: 168* Pragma Ident:: 169* Pragma Ignore_Pragma:: 170* Pragma Implementation_Defined:: 171* Pragma Implemented:: 172* Pragma Implicit_Packing:: 173* Pragma Import_Function:: 174* Pragma Import_Object:: 175* Pragma Import_Procedure:: 176* Pragma Import_Valued_Procedure:: 177* Pragma Independent:: 178* Pragma Independent_Components:: 179* Pragma Initial_Condition:: 180* Pragma Initialize_Scalars:: 181* Pragma Initializes:: 182* Pragma Inline_Always:: 183* Pragma Inline_Generic:: 184* Pragma Interface:: 185* Pragma Interface_Name:: 186* Pragma Interrupt_Handler:: 187* Pragma Interrupt_State:: 188* Pragma Invariant:: 189* Pragma Keep_Names:: 190* Pragma License:: 191* Pragma Link_With:: 192* Pragma Linker_Alias:: 193* Pragma Linker_Constructor:: 194* Pragma Linker_Destructor:: 195* Pragma Linker_Section:: 196* Pragma Lock_Free:: 197* Pragma Loop_Invariant:: 198* Pragma Loop_Optimize:: 199* Pragma Loop_Variant:: 200* Pragma Machine_Attribute:: 201* Pragma Main:: 202* Pragma Main_Storage:: 203* Pragma No_Body:: 204* Pragma No_Elaboration_Code_All:: 205* Pragma No_Inline:: 206* Pragma No_Return:: 207* Pragma No_Run_Time:: 208* Pragma No_Strict_Aliasing:: 209* Pragma No_Tagged_Streams:: 210* Pragma Normalize_Scalars:: 211* Pragma Obsolescent:: 212* Pragma Optimize_Alignment:: 213* Pragma Ordered:: 214* Pragma Overflow_Mode:: 215* Pragma Overriding_Renamings:: 216* Pragma Partition_Elaboration_Policy:: 217* Pragma Part_Of:: 218* Pragma Passive:: 219* Pragma Persistent_BSS:: 220* Pragma Polling:: 221* Pragma Post:: 222* Pragma Postcondition:: 223* Pragma Post_Class:: 224* Pragma Pre:: 225* Pragma Precondition:: 226* Pragma Predicate:: 227* Pragma Predicate_Failure:: 228* Pragma Preelaborable_Initialization:: 229* Pragma Prefix_Exception_Messages:: 230* Pragma Pre_Class:: 231* Pragma Priority_Specific_Dispatching:: 232* Pragma Profile:: 233* Pragma Profile_Warnings:: 234* Pragma Propagate_Exceptions:: 235* Pragma Provide_Shift_Operators:: 236* Pragma Psect_Object:: 237* Pragma Pure_Function:: 238* Pragma Rational:: 239* Pragma Ravenscar:: 240* Pragma Refined_Depends:: 241* Pragma Refined_Global:: 242* Pragma Refined_Post:: 243* Pragma Refined_State:: 244* Pragma Relative_Deadline:: 245* Pragma Remote_Access_Type:: 246* Pragma Restricted_Run_Time:: 247* Pragma Restriction_Warnings:: 248* Pragma Reviewable:: 249* Pragma Share_Generic:: 250* Pragma Shared:: 251* Pragma Short_Circuit_And_Or:: 252* Pragma Short_Descriptors:: 253* Pragma Simple_Storage_Pool_Type:: 254* Pragma Source_File_Name:: 255* Pragma Source_File_Name_Project:: 256* Pragma Source_Reference:: 257* Pragma SPARK_Mode:: 258* Pragma Static_Elaboration_Desired:: 259* Pragma Stream_Convert:: 260* Pragma Style_Checks:: 261* Pragma Subtitle:: 262* Pragma Suppress:: 263* Pragma Suppress_All:: 264* Pragma Suppress_Debug_Info:: 265* Pragma Suppress_Exception_Locations:: 266* Pragma Suppress_Initialization:: 267* Pragma Task_Name:: 268* Pragma Task_Storage:: 269* Pragma Test_Case:: 270* Pragma Thread_Local_Storage:: 271* Pragma Time_Slice:: 272* Pragma Title:: 273* Pragma Type_Invariant:: 274* Pragma Type_Invariant_Class:: 275* Pragma Unchecked_Union:: 276* Pragma Unevaluated_Use_Of_Old:: 277* Pragma Unimplemented_Unit:: 278* Pragma Universal_Aliasing:: 279* Pragma Universal_Data:: 280* Pragma Unmodified:: 281* Pragma Unreferenced:: 282* Pragma Unreferenced_Objects:: 283* Pragma Unreserve_All_Interrupts:: 284* Pragma Unsuppress:: 285* Pragma Use_VADS_Size:: 286* Pragma Validity_Checks:: 287* Pragma Volatile:: 288* Pragma Volatile_Full_Access:: 289* Pragma Volatile_Function:: 290* Pragma Warning_As_Error:: 291* Pragma Warnings:: 292* Pragma Weak_External:: 293* Pragma Wide_Character_Encoding:: 294 295Implementation Defined Aspects 296 297* Aspect Abstract_State:: 298* Annotate:: 299* Aspect Async_Readers:: 300* Aspect Async_Writers:: 301* Aspect Constant_After_Elaboration:: 302* Aspect Contract_Cases:: 303* Aspect Depends:: 304* Aspect Default_Initial_Condition:: 305* Aspect Dimension:: 306* Aspect Dimension_System:: 307* Aspect Disable_Controlled:: 308* Aspect Effective_Reads:: 309* Aspect Effective_Writes:: 310* Aspect Extensions_Visible:: 311* Aspect Favor_Top_Level:: 312* Aspect Ghost:: 313* Aspect Global:: 314* Aspect Initial_Condition:: 315* Aspect Initializes:: 316* Aspect Inline_Always:: 317* Aspect Invariant:: 318* Aspect Invariant'Class:: 319* Aspect Iterable:: 320* Aspect Linker_Section:: 321* Aspect Lock_Free:: 322* Aspect No_Elaboration_Code_All:: 323* Aspect No_Tagged_Streams:: 324* Aspect Object_Size:: 325* Aspect Obsolescent:: 326* Aspect Part_Of:: 327* Aspect Persistent_BSS:: 328* Aspect Predicate:: 329* Aspect Pure_Function:: 330* Aspect Refined_Depends:: 331* Aspect Refined_Global:: 332* Aspect Refined_Post:: 333* Aspect Refined_State:: 334* Aspect Remote_Access_Type:: 335* Aspect Scalar_Storage_Order:: 336* Aspect Shared:: 337* Aspect Simple_Storage_Pool:: 338* Aspect Simple_Storage_Pool_Type:: 339* Aspect SPARK_Mode:: 340* Aspect Suppress_Debug_Info:: 341* Aspect Suppress_Initialization:: 342* Aspect Test_Case:: 343* Aspect Thread_Local_Storage:: 344* Aspect Universal_Aliasing:: 345* Aspect Universal_Data:: 346* Aspect Unmodified:: 347* Aspect Unreferenced:: 348* Aspect Unreferenced_Objects:: 349* Aspect Value_Size:: 350* Aspect Volatile_Full_Access:: 351* Aspect Volatile_Function:: 352* Aspect Warnings:: 353 354Implementation Defined Attributes 355 356* Attribute Abort_Signal:: 357* Attribute Address_Size:: 358* Attribute Asm_Input:: 359* Attribute Asm_Output:: 360* Attribute Atomic_Always_Lock_Free:: 361* Attribute Bit:: 362* Attribute Bit_Position:: 363* Attribute Code_Address:: 364* Attribute Compiler_Version:: 365* Attribute Constrained:: 366* Attribute Default_Bit_Order:: 367* Attribute Default_Scalar_Storage_Order:: 368* Attribute Deref:: 369* Attribute Descriptor_Size:: 370* Attribute Elaborated:: 371* Attribute Elab_Body:: 372* Attribute Elab_Spec:: 373* Attribute Elab_Subp_Body:: 374* Attribute Emax:: 375* Attribute Enabled:: 376* Attribute Enum_Rep:: 377* Attribute Enum_Val:: 378* Attribute Epsilon:: 379* Attribute Fast_Math:: 380* Attribute Fixed_Value:: 381* Attribute From_Any:: 382* Attribute Has_Access_Values:: 383* Attribute Has_Discriminants:: 384* Attribute Img:: 385* Attribute Integer_Value:: 386* Attribute Invalid_Value:: 387* Attribute Iterable:: 388* Attribute Large:: 389* Attribute Library_Level:: 390* Attribute Lock_Free:: 391* Attribute Loop_Entry:: 392* Attribute Machine_Size:: 393* Attribute Mantissa:: 394* Attribute Maximum_Alignment:: 395* Attribute Mechanism_Code:: 396* Attribute Null_Parameter:: 397* Attribute Object_Size:: 398* Attribute Old:: 399* Attribute Passed_By_Reference:: 400* Attribute Pool_Address:: 401* Attribute Range_Length:: 402* Attribute Restriction_Set:: 403* Attribute Result:: 404* Attribute Safe_Emax:: 405* Attribute Safe_Large:: 406* Attribute Safe_Small:: 407* Attribute Scalar_Storage_Order:: 408* Attribute Simple_Storage_Pool:: 409* Attribute Small:: 410* Attribute Storage_Unit:: 411* Attribute Stub_Type:: 412* Attribute System_Allocator_Alignment:: 413* Attribute Target_Name:: 414* Attribute To_Address:: 415* Attribute To_Any:: 416* Attribute Type_Class:: 417* Attribute Type_Key:: 418* Attribute TypeCode:: 419* Attribute Unconstrained_Array:: 420* Attribute Universal_Literal_String:: 421* Attribute Unrestricted_Access:: 422* Attribute Update:: 423* Attribute Valid_Scalars:: 424* Attribute VADS_Size:: 425* Attribute Value_Size:: 426* Attribute Wchar_T_Size:: 427* Attribute Word_Size:: 428 429Standard and Implementation Defined Restrictions 430 431* Partition-Wide Restrictions:: 432* Program Unit Level Restrictions:: 433 434Partition-Wide Restrictions 435 436* Immediate_Reclamation:: 437* Max_Asynchronous_Select_Nesting:: 438* Max_Entry_Queue_Length:: 439* Max_Protected_Entries:: 440* Max_Select_Alternatives:: 441* Max_Storage_At_Blocking:: 442* Max_Task_Entries:: 443* Max_Tasks:: 444* No_Abort_Statements:: 445* No_Access_Parameter_Allocators:: 446* No_Access_Subprograms:: 447* No_Allocators:: 448* No_Anonymous_Allocators:: 449* No_Asynchronous_Control:: 450* No_Calendar:: 451* No_Coextensions:: 452* No_Default_Initialization:: 453* No_Delay:: 454* No_Dependence:: 455* No_Direct_Boolean_Operators:: 456* No_Dispatch:: 457* No_Dispatching_Calls:: 458* No_Dynamic_Attachment:: 459* No_Dynamic_Priorities:: 460* No_Entry_Calls_In_Elaboration_Code:: 461* No_Enumeration_Maps:: 462* No_Exception_Handlers:: 463* No_Exception_Propagation:: 464* No_Exception_Registration:: 465* No_Exceptions:: 466* No_Finalization:: 467* No_Fixed_Point:: 468* No_Floating_Point:: 469* No_Implicit_Conditionals:: 470* No_Implicit_Dynamic_Code:: 471* No_Implicit_Heap_Allocations:: 472* No_Implicit_Loops:: 473* No_Implicit_Protected_Object_Allocations:: 474* No_Implicit_Task_Allocations:: 475* No_Initialize_Scalars:: 476* No_IO:: 477* No_Local_Allocators:: 478* No_Local_Protected_Objects:: 479* No_Local_Timing_Events:: 480* No_Long_Long_Integers:: 481* No_Multiple_Elaboration:: 482* No_Nested_Finalization:: 483* No_Protected_Type_Allocators:: 484* No_Protected_Types:: 485* No_Recursion:: 486* No_Reentrancy:: 487* No_Relative_Delay:: 488* No_Requeue_Statements:: 489* No_Secondary_Stack:: 490* No_Select_Statements:: 491* No_Specific_Termination_Handlers:: 492* No_Specification_of_Aspect:: 493* No_Standard_Allocators_After_Elaboration:: 494* No_Standard_Storage_Pools:: 495* No_Stream_Optimizations:: 496* No_Streams:: 497* No_Task_Allocators:: 498* No_Task_At_Interrupt_Priority:: 499* No_Task_Attributes_Package:: 500* No_Task_Hierarchy:: 501* No_Task_Termination:: 502* No_Tasking:: 503* No_Terminate_Alternatives:: 504* No_Unchecked_Access:: 505* No_Unchecked_Conversion:: 506* No_Unchecked_Deallocation:: 507* No_Use_Of_Entity:: 508* Pure_Barriers:: 509* Simple_Barriers:: 510* Static_Priorities:: 511* Static_Storage_Size:: 512 513Program Unit Level Restrictions 514 515* No_Elaboration_Code:: 516* No_Dynamic_Sized_Objects:: 517* No_Entry_Queue:: 518* No_Implementation_Aspect_Specifications:: 519* No_Implementation_Attributes:: 520* No_Implementation_Identifiers:: 521* No_Implementation_Pragmas:: 522* No_Implementation_Restrictions:: 523* No_Implementation_Units:: 524* No_Implicit_Aliasing:: 525* No_Obsolescent_Features:: 526* No_Wide_Characters:: 527* SPARK_05:: 528 529Implementation Advice 530 531* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 532* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 533* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 534* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 535* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 536* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 537* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 538* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 539* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 540* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 541* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 542* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 543* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 544* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 545* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 546* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 547* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 548* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 549* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 550* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 551* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 552* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 553* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 554* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 555* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 556* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 557* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 558* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 559* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 560* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 561* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 562* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 563* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 564* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 565* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 566* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 567* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 568* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 569* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 570* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 571* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 572* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 573* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 574* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 575* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 576* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 577* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 578* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 579* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 580* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 581* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 582* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 583* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 584* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 585* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 586* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 587* RM F(7); COBOL Support: RM F 7 COBOL Support. 588* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 589* RM G; Numerics: RM G Numerics. 590* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 591* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 592* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 593* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 594* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 595 596Intrinsic Subprograms 597 598* Intrinsic Operators:: 599* Compilation_Date:: 600* Compilation_Time:: 601* Enclosing_Entity:: 602* Exception_Information:: 603* Exception_Message:: 604* Exception_Name:: 605* File:: 606* Line:: 607* Shifts and Rotates:: 608* Source_Location:: 609 610Representation Clauses and Pragmas 611 612* Alignment Clauses:: 613* Size Clauses:: 614* Storage_Size Clauses:: 615* Size of Variant Record Objects:: 616* Biased Representation:: 617* Value_Size and Object_Size Clauses:: 618* Component_Size Clauses:: 619* Bit_Order Clauses:: 620* Effect of Bit_Order on Byte Ordering:: 621* Pragma Pack for Arrays:: 622* Pragma Pack for Records:: 623* Record Representation Clauses:: 624* Handling of Records with Holes:: 625* Enumeration Clauses:: 626* Address Clauses:: 627* Use of Address Clauses for Memory-Mapped I/O:: 628* Effect of Convention on Representation:: 629* Conventions and Anonymous Access Types:: 630* Determining the Representations chosen by GNAT:: 631 632The Implementation of Standard I/O 633 634* Standard I/O Packages:: 635* FORM Strings:: 636* Direct_IO:: 637* Sequential_IO:: 638* Text_IO:: 639* Wide_Text_IO:: 640* Wide_Wide_Text_IO:: 641* Stream_IO:: 642* Text Translation:: 643* Shared Files:: 644* Filenames encoding:: 645* File content encoding:: 646* Open Modes:: 647* Operations on C Streams:: 648* Interfacing to C Streams:: 649 650Text_IO 651 652* Stream Pointer Positioning:: 653* Reading and Writing Non-Regular Files:: 654* Get_Immediate:: 655* Treating Text_IO Files as Streams:: 656* Text_IO Extensions:: 657* Text_IO Facilities for Unbounded Strings:: 658 659Wide_Text_IO 660 661* Stream Pointer Positioning: Stream Pointer Positioning<2>. 662* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 663 664Wide_Wide_Text_IO 665 666* Stream Pointer Positioning: Stream Pointer Positioning<3>. 667* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 668 669The GNAT Library 670 671* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 672* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 673* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 674* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 675* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 676* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 677* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 678* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 679* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 680* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 681* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 682* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 683* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 684* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 685* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 686* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 687* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 688* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 689* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 690* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 691* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 692* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 693* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 694* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 695* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 696* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 697* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 698* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 699* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 700* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 701* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 702* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 703* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 704* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 705* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 706* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 707* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 708* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 709* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 710* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 711* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 712* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 713* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 714* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 715* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 716* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 717* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 718* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 719* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 720* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 721* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 722* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 723* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 724* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 725* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 726* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 727* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 728* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 729* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 730* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 731* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 732* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 733* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 734* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 735* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 736* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 737* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 738* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 739* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 740* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 741* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 742* GNAT.Exceptions (g-expect.ads): GNAT Exceptions g-expect ads. 743* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 744* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 745* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 746* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 747* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 748* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 749* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 750* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 751* GNAT.IO (g-io.ads): GNAT IO g-io ads. 752* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 753* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 754* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 755* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 756* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 757* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 758* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 759* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 760* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 761* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 762* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 763* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 764* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 765* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 766* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 767* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 768* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 769* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 770* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 771* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 772* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 773* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 774* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 775* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 776* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 777* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 778* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 779* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 780* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 781* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 782* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 783* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 784* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 785* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 786* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 787* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 788* GNAT.Table (g-table.ads): GNAT Table g-table ads. 789* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 790* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 791* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 792* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 793* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 794* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 795* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 796* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 797* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 798* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 799* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 800* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 801* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 802* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 803* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 804* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 805* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 806* System.Assertions (s-assert.ads): System Assertions s-assert ads. 807* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 808* System.Memory (s-memory.ads): System Memory s-memory ads. 809* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 810* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 811* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 812* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 813* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 814* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 815* System.Rident (s-rident.ads): System Rident s-rident ads. 816* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 817* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 818* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 819* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 820 821Interfacing to Other Languages 822 823* Interfacing to C:: 824* Interfacing to C++:: 825* Interfacing to COBOL:: 826* Interfacing to Fortran:: 827* Interfacing to non-GNAT Ada code:: 828 829Implementation of Specific Ada Features 830 831* Machine Code Insertions:: 832* GNAT Implementation of Tasking:: 833* GNAT Implementation of Shared Passive Packages:: 834* Code Generation for Array Aggregates:: 835* The Size of Discriminated Records with Default Discriminants:: 836* Strict Conformance to the Ada Reference Manual:: 837 838GNAT Implementation of Tasking 839 840* Mapping Ada Tasks onto the Underlying Kernel Threads:: 841* Ensuring Compliance with the Real-Time Annex:: 842 843Code Generation for Array Aggregates 844 845* Static constant aggregates with static bounds:: 846* Constant aggregates with unconstrained nominal types:: 847* Aggregates with static bounds:: 848* Aggregates with nonstatic bounds:: 849* Aggregates in assignment statements:: 850 851Obsolescent Features 852 853* pragma No_Run_Time:: 854* pragma Ravenscar:: 855* pragma Restricted_Run_Time:: 856* pragma Task_Info:: 857* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 858 859Compatibility and Porting Guide 860 861* Writing Portable Fixed-Point Declarations:: 862* Compatibility with Ada 83:: 863* Compatibility between Ada 95 and Ada 2005:: 864* Implementation-dependent characteristics:: 865* Compatibility with Other Ada Systems:: 866* Representation Clauses:: 867* Compatibility with HP Ada 83:: 868 869Compatibility with Ada 83 870 871* Legal Ada 83 programs that are illegal in Ada 95:: 872* More deterministic semantics:: 873* Changed semantics:: 874* Other language compatibility issues:: 875 876Implementation-dependent characteristics 877 878* Implementation-defined pragmas:: 879* Implementation-defined attributes:: 880* Libraries:: 881* Elaboration order:: 882* Target-specific aspects:: 883 884@end detailmenu 885@end menu 886 887@node About This Guide,Implementation Defined Pragmas,Top,Top 888@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} 889@chapter About This Guide 890 891 892 893This manual contains useful information in writing programs using the 894GNAT compiler. It includes information on implementation dependent 895characteristics of GNAT, including all the information required by 896Annex M of the Ada language standard. 897 898GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 899invoked in Ada 83 compatibility mode. 900By default, GNAT assumes Ada 2012, 901but you can override with a compiler switch 902to explicitly specify the language version. 903(Please refer to the @emph{GNAT User's Guide} for details on these switches.) 904Throughout this manual, references to 'Ada' without a year suffix 905apply to all the Ada versions of the language. 906 907Ada is designed to be highly portable. 908In general, a program will have the same effect even when compiled by 909different compilers on different platforms. 910However, since Ada is designed to be used in a 911wide variety of applications, it also contains a number of system 912dependent features to be used in interfacing to the external world. 913 914@geindex Implementation-dependent features 915 916@geindex Portability 917 918Note: Any program that makes use of implementation-dependent features 919may be non-portable. You should follow good programming practice and 920isolate and clearly document any sections of your program that make use 921of these features in a non-portable manner. 922 923@menu 924* What This Reference Manual Contains:: 925* Conventions:: 926* Related Information:: 927 928@end menu 929 930@node What This Reference Manual Contains,Conventions,,About This Guide 931@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 932@section What This Reference Manual Contains 933 934 935This reference manual contains the following chapters: 936 937 938@itemize * 939 940@item 941@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 942pragmas, which can be used to extend and enhance the functionality of the 943compiler. 944 945@item 946@ref{8,,Implementation Defined Attributes}, lists GNAT 947implementation-dependent attributes, which can be used to extend and 948enhance the functionality of the compiler. 949 950@item 951@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 952implementation-dependent restrictions, which can be used to extend and 953enhance the functionality of the compiler. 954 955@item 956@ref{a,,Implementation Advice}, provides information on generally 957desirable behavior which are not requirements that all compilers must 958follow since it cannot be provided on all systems, or which may be 959undesirable on some systems. 960 961@item 962@ref{b,,Implementation Defined Characteristics}, provides a guide to 963minimizing implementation dependent features. 964 965@item 966@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 967implemented by GNAT, and how they can be imported into user 968application programs. 969 970@item 971@ref{d,,Representation Clauses and Pragmas}, describes in detail the 972way that GNAT represents data, and in particular the exact set 973of representation clauses and pragmas that is accepted. 974 975@item 976@ref{e,,Standard Library Routines}, provides a listing of packages and a 977brief description of the functionality that is provided by Ada's 978extensive set of standard library routines as implemented by GNAT. 979 980@item 981@ref{f,,The Implementation of Standard I/O}, details how the GNAT 982implementation of the input-output facilities. 983 984@item 985@ref{10,,The GNAT Library}, is a catalog of packages that complement 986the Ada predefined library. 987 988@item 989@ref{11,,Interfacing to Other Languages}, describes how programs 990written in Ada using GNAT can be interfaced to other programming 991languages. 992 993@item 994@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 995of the specialized needs annexes. 996 997@item 998@ref{13,,Implementation of Specific Ada Features}, discusses issues related 999to GNAT's implementation of machine code insertions, tasking, and several 1000other features. 1001 1002@item 1003@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1004GNAT implementation of the Ada 2012 language standard. 1005 1006@item 1007@ref{15,,Obsolescent Features} documents implementation dependent features, 1008including pragmas and attributes, which are considered obsolescent, since 1009there are other preferred ways of achieving the same results. These 1010obsolescent forms are retained for backwards compatibility. 1011 1012@item 1013@ref{16,,Compatibility and Porting Guide} presents some guidelines for 1014developing portable Ada code, describes the compatibility issues that 1015may arise between GNAT and other Ada compilation systems (including those 1016for Ada 83), and shows how GNAT can expedite porting applications 1017developed in other Ada environments. 1018 1019@item 1020@ref{1,,GNU Free Documentation License} contains the license for this document. 1021@end itemize 1022 1023@geindex Ada 95 Language Reference Manual 1024 1025@geindex Ada 2005 Language Reference Manual 1026 1027This reference manual assumes a basic familiarity with the Ada 95 language, as 1028described in the 1029@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1030It does not require knowledge of the new features introduced by Ada 2005 or 1031Ada 2012. 1032All three reference manuals are included in the GNAT documentation 1033package. 1034 1035@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1036@anchor{gnat_rm/about_this_guide conventions}@anchor{17} 1037@section Conventions 1038 1039 1040@geindex Conventions 1041@geindex typographical 1042 1043@geindex Typographical conventions 1044 1045Following are examples of the typographical and graphic conventions used 1046in this guide: 1047 1048 1049@itemize * 1050 1051@item 1052@cite{Functions}, @cite{utility program names}, @cite{standard names}, 1053and @cite{classes}. 1054 1055@item 1056@cite{Option flags} 1057 1058@item 1059@code{File names} 1060 1061@item 1062@cite{Variables} 1063 1064@item 1065@emph{Emphasis} 1066 1067@item 1068[optional information or parameters] 1069 1070@item 1071Examples are described by text 1072 1073@example 1074and then shown this way. 1075@end example 1076 1077@item 1078Commands that are entered by the user are shown as preceded by a prompt string 1079comprising the @code{$} character followed by a space. 1080@end itemize 1081 1082@node Related Information,,Conventions,About This Guide 1083@anchor{gnat_rm/about_this_guide related-information}@anchor{18} 1084@section Related Information 1085 1086 1087See the following documents for further information on GNAT: 1088 1089 1090@itemize * 1091 1092@item 1093@cite{GNAT User's Guide for Native Platforms}, 1094which provides information on how to use the 1095GNAT development environment. 1096 1097@item 1098@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1099 1100@item 1101@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1102of the Ada 95 standard. The annotations describe 1103detailed aspects of the design decision, and in particular contain useful 1104sections on Ada 83 compatibility. 1105 1106@item 1107@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1108 1109@item 1110@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1111of the Ada 2005 standard. The annotations describe 1112detailed aspects of the design decision. 1113 1114@item 1115@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1116 1117@item 1118@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1119which contains specific information on compatibility between GNAT and 1120DEC Ada 83 systems. 1121 1122@item 1123@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1124describes in detail the pragmas and attributes provided by the DEC Ada 83 1125compiler system. 1126@end itemize 1127 1128@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1129@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} 1130@chapter Implementation Defined Pragmas 1131 1132 1133Ada defines a set of pragmas that can be used to supply additional 1134information to the compiler. These language defined pragmas are 1135implemented in GNAT and work as described in the Ada Reference Manual. 1136 1137In addition, Ada allows implementations to define additional pragmas 1138whose meaning is defined by the implementation. GNAT provides a number 1139of these implementation-defined pragmas, which can be used to extend 1140and enhance the functionality of the compiler. This section of the GNAT 1141Reference Manual describes these additional pragmas. 1142 1143Note that any program using these pragmas might not be portable to other 1144compilers (although GNAT implements this set of pragmas on all 1145platforms). Therefore if portability to other compilers is an important 1146consideration, the use of these pragmas should be minimized. 1147 1148@menu 1149* Pragma Abort_Defer:: 1150* Pragma Abstract_State:: 1151* Pragma Ada_83:: 1152* Pragma Ada_95:: 1153* Pragma Ada_05:: 1154* Pragma Ada_2005:: 1155* Pragma Ada_12:: 1156* Pragma Ada_2012:: 1157* Pragma Allow_Integer_Address:: 1158* Pragma Annotate:: 1159* Pragma Assert:: 1160* Pragma Assert_And_Cut:: 1161* Pragma Assertion_Policy:: 1162* Pragma Assume:: 1163* Pragma Assume_No_Invalid_Values:: 1164* Pragma Async_Readers:: 1165* Pragma Async_Writers:: 1166* Pragma Attribute_Definition:: 1167* Pragma C_Pass_By_Copy:: 1168* Pragma Check:: 1169* Pragma Check_Float_Overflow:: 1170* Pragma Check_Name:: 1171* Pragma Check_Policy:: 1172* Pragma Comment:: 1173* Pragma Common_Object:: 1174* Pragma Compile_Time_Error:: 1175* Pragma Compile_Time_Warning:: 1176* Pragma Compiler_Unit:: 1177* Pragma Compiler_Unit_Warning:: 1178* Pragma Complete_Representation:: 1179* Pragma Complex_Representation:: 1180* Pragma Component_Alignment:: 1181* Pragma Constant_After_Elaboration:: 1182* Pragma Contract_Cases:: 1183* Pragma Convention_Identifier:: 1184* Pragma CPP_Class:: 1185* Pragma CPP_Constructor:: 1186* Pragma CPP_Virtual:: 1187* Pragma CPP_Vtable:: 1188* Pragma CPU:: 1189* Pragma Default_Initial_Condition:: 1190* Pragma Debug:: 1191* Pragma Debug_Policy:: 1192* Pragma Default_Scalar_Storage_Order:: 1193* Pragma Default_Storage_Pool:: 1194* Pragma Depends:: 1195* Pragma Detect_Blocking:: 1196* Pragma Disable_Atomic_Synchronization:: 1197* Pragma Dispatching_Domain:: 1198* Pragma Effective_Reads:: 1199* Pragma Effective_Writes:: 1200* Pragma Elaboration_Checks:: 1201* Pragma Eliminate:: 1202* Pragma Enable_Atomic_Synchronization:: 1203* Pragma Export_Function:: 1204* Pragma Export_Object:: 1205* Pragma Export_Procedure:: 1206* Pragma Export_Value:: 1207* Pragma Export_Valued_Procedure:: 1208* Pragma Extend_System:: 1209* Pragma Extensions_Allowed:: 1210* Pragma Extensions_Visible:: 1211* Pragma External:: 1212* Pragma External_Name_Casing:: 1213* Pragma Fast_Math:: 1214* Pragma Favor_Top_Level:: 1215* Pragma Finalize_Storage_Only:: 1216* Pragma Float_Representation:: 1217* Pragma Ghost:: 1218* Pragma Global:: 1219* Pragma Ident:: 1220* Pragma Ignore_Pragma:: 1221* Pragma Implementation_Defined:: 1222* Pragma Implemented:: 1223* Pragma Implicit_Packing:: 1224* Pragma Import_Function:: 1225* Pragma Import_Object:: 1226* Pragma Import_Procedure:: 1227* Pragma Import_Valued_Procedure:: 1228* Pragma Independent:: 1229* Pragma Independent_Components:: 1230* Pragma Initial_Condition:: 1231* Pragma Initialize_Scalars:: 1232* Pragma Initializes:: 1233* Pragma Inline_Always:: 1234* Pragma Inline_Generic:: 1235* Pragma Interface:: 1236* Pragma Interface_Name:: 1237* Pragma Interrupt_Handler:: 1238* Pragma Interrupt_State:: 1239* Pragma Invariant:: 1240* Pragma Keep_Names:: 1241* Pragma License:: 1242* Pragma Link_With:: 1243* Pragma Linker_Alias:: 1244* Pragma Linker_Constructor:: 1245* Pragma Linker_Destructor:: 1246* Pragma Linker_Section:: 1247* Pragma Lock_Free:: 1248* Pragma Loop_Invariant:: 1249* Pragma Loop_Optimize:: 1250* Pragma Loop_Variant:: 1251* Pragma Machine_Attribute:: 1252* Pragma Main:: 1253* Pragma Main_Storage:: 1254* Pragma No_Body:: 1255* Pragma No_Elaboration_Code_All:: 1256* Pragma No_Inline:: 1257* Pragma No_Return:: 1258* Pragma No_Run_Time:: 1259* Pragma No_Strict_Aliasing:: 1260* Pragma No_Tagged_Streams:: 1261* Pragma Normalize_Scalars:: 1262* Pragma Obsolescent:: 1263* Pragma Optimize_Alignment:: 1264* Pragma Ordered:: 1265* Pragma Overflow_Mode:: 1266* Pragma Overriding_Renamings:: 1267* Pragma Partition_Elaboration_Policy:: 1268* Pragma Part_Of:: 1269* Pragma Passive:: 1270* Pragma Persistent_BSS:: 1271* Pragma Polling:: 1272* Pragma Post:: 1273* Pragma Postcondition:: 1274* Pragma Post_Class:: 1275* Pragma Pre:: 1276* Pragma Precondition:: 1277* Pragma Predicate:: 1278* Pragma Predicate_Failure:: 1279* Pragma Preelaborable_Initialization:: 1280* Pragma Prefix_Exception_Messages:: 1281* Pragma Pre_Class:: 1282* Pragma Priority_Specific_Dispatching:: 1283* Pragma Profile:: 1284* Pragma Profile_Warnings:: 1285* Pragma Propagate_Exceptions:: 1286* Pragma Provide_Shift_Operators:: 1287* Pragma Psect_Object:: 1288* Pragma Pure_Function:: 1289* Pragma Rational:: 1290* Pragma Ravenscar:: 1291* Pragma Refined_Depends:: 1292* Pragma Refined_Global:: 1293* Pragma Refined_Post:: 1294* Pragma Refined_State:: 1295* Pragma Relative_Deadline:: 1296* Pragma Remote_Access_Type:: 1297* Pragma Restricted_Run_Time:: 1298* Pragma Restriction_Warnings:: 1299* Pragma Reviewable:: 1300* Pragma Share_Generic:: 1301* Pragma Shared:: 1302* Pragma Short_Circuit_And_Or:: 1303* Pragma Short_Descriptors:: 1304* Pragma Simple_Storage_Pool_Type:: 1305* Pragma Source_File_Name:: 1306* Pragma Source_File_Name_Project:: 1307* Pragma Source_Reference:: 1308* Pragma SPARK_Mode:: 1309* Pragma Static_Elaboration_Desired:: 1310* Pragma Stream_Convert:: 1311* Pragma Style_Checks:: 1312* Pragma Subtitle:: 1313* Pragma Suppress:: 1314* Pragma Suppress_All:: 1315* Pragma Suppress_Debug_Info:: 1316* Pragma Suppress_Exception_Locations:: 1317* Pragma Suppress_Initialization:: 1318* Pragma Task_Name:: 1319* Pragma Task_Storage:: 1320* Pragma Test_Case:: 1321* Pragma Thread_Local_Storage:: 1322* Pragma Time_Slice:: 1323* Pragma Title:: 1324* Pragma Type_Invariant:: 1325* Pragma Type_Invariant_Class:: 1326* Pragma Unchecked_Union:: 1327* Pragma Unevaluated_Use_Of_Old:: 1328* Pragma Unimplemented_Unit:: 1329* Pragma Universal_Aliasing:: 1330* Pragma Universal_Data:: 1331* Pragma Unmodified:: 1332* Pragma Unreferenced:: 1333* Pragma Unreferenced_Objects:: 1334* Pragma Unreserve_All_Interrupts:: 1335* Pragma Unsuppress:: 1336* Pragma Use_VADS_Size:: 1337* Pragma Validity_Checks:: 1338* Pragma Volatile:: 1339* Pragma Volatile_Full_Access:: 1340* Pragma Volatile_Function:: 1341* Pragma Warning_As_Error:: 1342* Pragma Warnings:: 1343* Pragma Weak_External:: 1344* Pragma Wide_Character_Encoding:: 1345 1346@end menu 1347 1348@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1349@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b} 1350@section Pragma Abort_Defer 1351 1352 1353@geindex Deferring aborts 1354 1355Syntax: 1356 1357@example 1358pragma Abort_Defer; 1359@end example 1360 1361This pragma must appear at the start of the statement sequence of a 1362handled sequence of statements (right after the @cite{begin}). It has 1363the effect of deferring aborts for the sequence of statements (but not 1364for the declarations or handlers, if any, associated with this statement 1365sequence). 1366 1367@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas 1368@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c} 1369@section Pragma Abstract_State 1370 1371 1372Syntax: 1373 1374@example 1375pragma Abstract_State (ABSTRACT_STATE_LIST); 1376 1377ABSTRACT_STATE_LIST ::= 1378 null 1379 | STATE_NAME_WITH_OPTIONS 1380 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1381 1382STATE_NAME_WITH_OPTIONS ::= 1383 STATE_NAME 1384 | (STATE_NAME with OPTION_LIST) 1385 1386OPTION_LIST ::= OPTION @{, OPTION@} 1387 1388OPTION ::= 1389 SIMPLE_OPTION 1390 | NAME_VALUE_OPTION 1391 1392SIMPLE_OPTION ::= Ghost | Synchronous 1393 1394NAME_VALUE_OPTION ::= 1395 Part_Of => ABSTRACT_STATE 1396 | External [=> EXTERNAL_PROPERTY_LIST] 1397 1398EXTERNAL_PROPERTY_LIST ::= 1399 EXTERNAL_PROPERTY 1400 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1401 1402EXTERNAL_PROPERTY ::= 1403 Async_Readers [=> boolean_EXPRESSION] 1404 | Async_Writers [=> boolean_EXPRESSION] 1405 | Effective_Reads [=> boolean_EXPRESSION] 1406 | Effective_Writes [=> boolean_EXPRESSION] 1407 others => boolean_EXPRESSION 1408 1409STATE_NAME ::= defining_identifier 1410 1411ABSTRACT_STATE ::= name 1412@end example 1413 1414For the semantics of this pragma, see the entry for aspect @cite{Abstract_State} in 1415the SPARK 2014 Reference Manual, section 7.1.4. 1416 1417@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas 1418@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1d} 1419@section Pragma Ada_83 1420 1421 1422Syntax: 1423 1424@example 1425pragma Ada_83; 1426@end example 1427 1428A configuration pragma that establishes Ada 83 mode for the unit to 1429which it applies, regardless of the mode set by the command line 1430switches. In Ada 83 mode, GNAT attempts to be as compatible with 1431the syntax and semantics of Ada 83, as defined in the original Ada 143283 Reference Manual as possible. In particular, the keywords added by Ada 95 1433and Ada 2005 are not recognized, optional package bodies are allowed, 1434and generics may name types with unknown discriminants without using 1435the @cite{(<>)} notation. In addition, some but not all of the additional 1436restrictions of Ada 83 are enforced. 1437 1438Ada 83 mode is intended for two purposes. Firstly, it allows existing 1439Ada 83 code to be compiled and adapted to GNAT with less effort. 1440Secondly, it aids in keeping code backwards compatible with Ada 83. 1441However, there is no guarantee that code that is processed correctly 1442by GNAT in Ada 83 mode will in fact compile and execute with an Ada 144383 compiler, since GNAT does not enforce all the additional checks 1444required by Ada 83. 1445 1446@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1447@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{1e} 1448@section Pragma Ada_95 1449 1450 1451Syntax: 1452 1453@example 1454pragma Ada_95; 1455@end example 1456 1457A configuration pragma that establishes Ada 95 mode for the unit to which 1458it applies, regardless of the mode set by the command line switches. 1459This mode is set automatically for the @cite{Ada} and @cite{System} 1460packages and their children, so you need not specify it in these 1461contexts. This pragma is useful when writing a reusable component that 1462itself uses Ada 95 features, but which is intended to be usable from 1463either Ada 83 or Ada 95 programs. 1464 1465@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1466@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{1f} 1467@section Pragma Ada_05 1468 1469 1470Syntax: 1471 1472@example 1473pragma Ada_05; 1474pragma Ada_05 (local_NAME); 1475@end example 1476 1477A configuration pragma that establishes Ada 2005 mode for the unit to which 1478it applies, regardless of the mode set by the command line switches. 1479This pragma is useful when writing a reusable component that 1480itself uses Ada 2005 features, but which is intended to be usable from 1481either Ada 83 or Ada 95 programs. 1482 1483The one argument form (which is not a configuration pragma) 1484is used for managing the transition from 1485Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1486as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1487mode will generate a warning. In addition, in Ada_83 or Ada_95 1488mode, a preference rule is established which does not choose 1489such an entity unless it is unambiguously specified. This avoids 1490extra subprograms marked this way from generating ambiguities in 1491otherwise legal pre-Ada_2005 programs. The one argument form is 1492intended for exclusive use in the GNAT run-time library. 1493 1494@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1495@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{20} 1496@section Pragma Ada_2005 1497 1498 1499Syntax: 1500 1501@example 1502pragma Ada_2005; 1503@end example 1504 1505This configuration pragma is a synonym for pragma Ada_05 and has the 1506same syntax and effect. 1507 1508@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1509@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{21} 1510@section Pragma Ada_12 1511 1512 1513Syntax: 1514 1515@example 1516pragma Ada_12; 1517pragma Ada_12 (local_NAME); 1518@end example 1519 1520A configuration pragma that establishes Ada 2012 mode for the unit to which 1521it applies, regardless of the mode set by the command line switches. 1522This mode is set automatically for the @cite{Ada} and @cite{System} 1523packages and their children, so you need not specify it in these 1524contexts. This pragma is useful when writing a reusable component that 1525itself uses Ada 2012 features, but which is intended to be usable from 1526Ada 83, Ada 95, or Ada 2005 programs. 1527 1528The one argument form, which is not a configuration pragma, 1529is used for managing the transition from Ada 15302005 to Ada 2012 in the run-time library. If an entity is marked 1531as Ada_201 only, then referencing the entity in any pre-Ada_2012 1532mode will generate a warning. In addition, in any pre-Ada_2012 1533mode, a preference rule is established which does not choose 1534such an entity unless it is unambiguously specified. This avoids 1535extra subprograms marked this way from generating ambiguities in 1536otherwise legal pre-Ada_2012 programs. The one argument form is 1537intended for exclusive use in the GNAT run-time library. 1538 1539@node Pragma Ada_2012,Pragma Allow_Integer_Address,Pragma Ada_12,Implementation Defined Pragmas 1540@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{22} 1541@section Pragma Ada_2012 1542 1543 1544Syntax: 1545 1546@example 1547pragma Ada_2012; 1548@end example 1549 1550This configuration pragma is a synonym for pragma Ada_12 and has the 1551same syntax and effect. 1552 1553@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Ada_2012,Implementation Defined Pragmas 1554@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{23} 1555@section Pragma Allow_Integer_Address 1556 1557 1558Syntax: 1559 1560@example 1561pragma Allow_Integer_Address; 1562@end example 1563 1564In almost all versions of GNAT, @cite{System.Address} is a private 1565type in accordance with the implementation advice in the RM. This 1566means that integer values, 1567in particular integer literals, are not allowed as address values. 1568If the configuration pragma 1569@cite{Allow_Integer_Address} is given, then integer expressions may 1570be used anywhere a value of type @cite{System.Address} is required. 1571The effect is to introduce an implicit unchecked conversion from the 1572integer value to type @cite{System.Address}. The reverse case of using 1573an address where an integer type is required is handled analogously. 1574The following example compiles without errors: 1575 1576@example 1577pragma Allow_Integer_Address; 1578with System; use System; 1579package AddrAsInt is 1580 X : Integer; 1581 Y : Integer; 1582 for X'Address use 16#1240#; 1583 for Y use at 16#3230#; 1584 m : Address := 16#4000#; 1585 n : constant Address := 4000; 1586 p : constant Address := Address (X + Y); 1587 v : Integer := y'Address; 1588 w : constant Integer := Integer (Y'Address); 1589 type R is new integer; 1590 RR : R := 1000; 1591 Z : Integer; 1592 for Z'Address use RR; 1593end AddrAsInt; 1594@end example 1595 1596Note that pragma @cite{Allow_Integer_Address} is ignored if @cite{System.Address} 1597is not a private type. In implementations of @cite{GNAT} where 1598System.Address is a visible integer type, 1599this pragma serves no purpose but is ignored 1600rather than rejected to allow common sets of sources to be used 1601in the two situations. 1602 1603@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1604@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{24} 1605@section Pragma Annotate 1606 1607 1608Syntax: 1609 1610@example 1611pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1612 1613ARG ::= NAME | EXPRESSION 1614@end example 1615 1616This pragma is used to annotate programs. @cite{identifier} identifies 1617the type of annotation. GNAT verifies that it is an identifier, but does 1618not otherwise analyze it. The second optional identifier is also left 1619unanalyzed, and by convention is used to control the action of the tool to 1620which the annotation is addressed. The remaining @cite{arg} arguments 1621can be either string literals or more generally expressions. 1622String literals are assumed to be either of type 1623@cite{Standard.String} or else @cite{Wide_String} or @cite{Wide_Wide_String} 1624depending on the character literals they contain. 1625All other kinds of arguments are analyzed as expressions, and must be 1626unambiguous. The last argument if present must have the identifier 1627@cite{Entity} and GNAT verifies that a local name is given. 1628 1629The analyzed pragma is retained in the tree, but not otherwise processed 1630by any part of the GNAT compiler, except to generate corresponding note 1631lines in the generated ALI file. For the format of these note lines, see 1632the compiler source file lib-writ.ads. This pragma is intended for use by 1633external tools, including ASIS. The use of pragma Annotate does not 1634affect the compilation process in any way. This pragma may be used as 1635a configuration pragma. 1636 1637@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1638@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{25} 1639@section Pragma Assert 1640 1641 1642Syntax: 1643 1644@example 1645pragma Assert ( 1646 boolean_EXPRESSION 1647 [, string_EXPRESSION]); 1648@end example 1649 1650The effect of this pragma depends on whether the corresponding command 1651line switch is set to activate assertions. The pragma expands into code 1652equivalent to the following: 1653 1654@example 1655if assertions-enabled then 1656 if not boolean_EXPRESSION then 1657 System.Assertions.Raise_Assert_Failure 1658 (string_EXPRESSION); 1659 end if; 1660end if; 1661@end example 1662 1663The string argument, if given, is the message that will be associated 1664with the exception occurrence if the exception is raised. If no second 1665argument is given, the default message is @cite{file}:@cite{nnn}, 1666where @cite{file} is the name of the source file containing the assert, 1667and @cite{nnn} is the line number of the assert. 1668 1669Note that, as with the @cite{if} statement to which it is equivalent, the 1670type of the expression is either @cite{Standard.Boolean}, or any type derived 1671from this standard type. 1672 1673Assert checks can be either checked or ignored. By default they are ignored. 1674They will be checked if either the command line switch @emph{-gnata} is 1675used, or if an @cite{Assertion_Policy} or @cite{Check_Policy} pragma is used 1676to enable @cite{Assert_Checks}. 1677 1678If assertions are ignored, then there 1679is no run-time effect (and in particular, any side effects from the 1680expression will not occur at run time). (The expression is still 1681analyzed at compile time, and may cause types to be frozen if they are 1682mentioned here for the first time). 1683 1684If assertions are checked, then the given expression is tested, and if 1685it is @cite{False} then @cite{System.Assertions.Raise_Assert_Failure} is called 1686which results in the raising of @cite{Assert_Failure} with the given message. 1687 1688You should generally avoid side effects in the expression arguments of 1689this pragma, because these side effects will turn on and off with the 1690setting of the assertions mode, resulting in assertions that have an 1691effect on the program. However, the expressions are analyzed for 1692semantic correctness whether or not assertions are enabled, so turning 1693assertions on and off cannot affect the legality of a program. 1694 1695Note that the implementation defined policy @cite{DISABLE}, given in a 1696pragma @cite{Assertion_Policy}, can be used to suppress this semantic analysis. 1697 1698Note: this is a standard language-defined pragma in versions 1699of Ada from 2005 on. In GNAT, it is implemented in all versions 1700of Ada, and the DISABLE policy is an implementation-defined 1701addition. 1702 1703@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1704@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{26} 1705@section Pragma Assert_And_Cut 1706 1707 1708Syntax: 1709 1710@example 1711pragma Assert_And_Cut ( 1712 boolean_EXPRESSION 1713 [, string_EXPRESSION]); 1714@end example 1715 1716The effect of this pragma is identical to that of pragma @cite{Assert}, 1717except that in an @cite{Assertion_Policy} pragma, the identifier 1718@cite{Assert_And_Cut} is used to control whether it is ignored or checked 1719(or disabled). 1720 1721The intention is that this be used within a subprogram when the 1722given test expresion sums up all the work done so far in the 1723subprogram, so that the rest of the subprogram can be verified 1724(informally or formally) using only the entry preconditions, 1725and the expression in this pragma. This allows dividing up 1726a subprogram into sections for the purposes of testing or 1727formal verification. The pragma also serves as useful 1728documentation. 1729 1730@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1731@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{27} 1732@section Pragma Assertion_Policy 1733 1734 1735Syntax: 1736 1737@example 1738pragma Assertion_Policy (CHECK | DISABLE | IGNORE); 1739 1740pragma Assertion_Policy ( 1741 ASSERTION_KIND => POLICY_IDENTIFIER 1742 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1743 1744ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1745 1746RM_ASSERTION_KIND ::= Assert | 1747 Static_Predicate | 1748 Dynamic_Predicate | 1749 Pre | 1750 Pre'Class | 1751 Post | 1752 Post'Class | 1753 Type_Invariant | 1754 Type_Invariant'Class 1755 1756ID_ASSERTION_KIND ::= Assertions | 1757 Assert_And_Cut | 1758 Assume | 1759 Contract_Cases | 1760 Debug | 1761 Invariant | 1762 Invariant'Class | 1763 Loop_Invariant | 1764 Loop_Variant | 1765 Postcondition | 1766 Precondition | 1767 Predicate | 1768 Refined_Post | 1769 Statement_Assertions 1770 1771POLICY_IDENTIFIER ::= Check | Disable | Ignore 1772@end example 1773 1774This is a standard Ada 2012 pragma that is available as an 1775implementation-defined pragma in earlier versions of Ada. 1776The assertion kinds @cite{RM_ASSERTION_KIND} are those defined in 1777the Ada standard. The assertion kinds @cite{ID_ASSERTION_KIND} 1778are implementation defined additions recognized by the GNAT compiler. 1779 1780The pragma applies in both cases to pragmas and aspects with matching 1781names, e.g. @cite{Pre} applies to the Pre aspect, and @cite{Precondition} 1782applies to both the @cite{Precondition} pragma 1783and the aspect @cite{Precondition}. Note that the identifiers for 1784pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 1785Pre_Class and Post_Class), since these pragmas are intended to be 1786identical to the corresponding aspects). 1787 1788If the policy is @cite{CHECK}, then assertions are enabled, i.e. 1789the corresponding pragma or aspect is activated. 1790If the policy is @cite{IGNORE}, then assertions are ignored, i.e. 1791the corresponding pragma or aspect is deactivated. 1792This pragma overrides the effect of the @emph{-gnata} switch on the 1793command line. 1794 1795The implementation defined policy @cite{DISABLE} is like 1796@cite{IGNORE} except that it completely disables semantic 1797checking of the corresponding pragma or aspect. This is 1798useful when the pragma or aspect argument references subprograms 1799in a with'ed package which is replaced by a dummy package 1800for the final build. 1801 1802The implementation defined assertion kind @cite{Assertions} applies to all 1803assertion kinds. The form with no assertion kind given implies this 1804choice, so it applies to all assertion kinds (RM defined, and 1805implementation defined). 1806 1807The implementation defined assertion kind @cite{Statement_Assertions} 1808applies to @cite{Assert}, @cite{Assert_And_Cut}, 1809@cite{Assume}, @cite{Loop_Invariant}, and @cite{Loop_Variant}. 1810 1811@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 1812@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{28} 1813@section Pragma Assume 1814 1815 1816Syntax: 1817 1818@example 1819pragma Assume ( 1820 boolean_EXPRESSION 1821 [, string_EXPRESSION]); 1822@end example 1823 1824The effect of this pragma is identical to that of pragma @cite{Assert}, 1825except that in an @cite{Assertion_Policy} pragma, the identifier 1826@cite{Assume} is used to control whether it is ignored or checked 1827(or disabled). 1828 1829The intention is that this be used for assumptions about the 1830external environment. So you cannot expect to verify formally 1831or informally that the condition is met, this must be 1832established by examining things outside the program itself. 1833For example, we may have code that depends on the size of 1834@cite{Long_Long_Integer} being at least 64. So we could write: 1835 1836@example 1837pragma Assume (Long_Long_Integer'Size >= 64); 1838@end example 1839 1840This assumption cannot be proved from the program itself, 1841but it acts as a useful run-time check that the assumption 1842is met, and documents the need to ensure that it is met by 1843reference to information outside the program. 1844 1845@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 1846@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{29} 1847@section Pragma Assume_No_Invalid_Values 1848 1849 1850@geindex Invalid representations 1851 1852@geindex Invalid values 1853 1854Syntax: 1855 1856@example 1857pragma Assume_No_Invalid_Values (On | Off); 1858@end example 1859 1860This is a configuration pragma that controls the assumptions made by the 1861compiler about the occurrence of invalid representations (invalid values) 1862in the code. 1863 1864The default behavior (corresponding to an Off argument for this pragma), is 1865to assume that values may in general be invalid unless the compiler can 1866prove they are valid. Consider the following example: 1867 1868@example 1869V1 : Integer range 1 .. 10; 1870V2 : Integer range 11 .. 20; 1871... 1872for J in V2 .. V1 loop 1873 ... 1874end loop; 1875@end example 1876 1877if V1 and V2 have valid values, then the loop is known at compile 1878time not to execute since the lower bound must be greater than the 1879upper bound. However in default mode, no such assumption is made, 1880and the loop may execute. If @cite{Assume_No_Invalid_Values (On)} 1881is given, the compiler will assume that any occurrence of a variable 1882other than in an explicit @cite{'Valid} test always has a valid 1883value, and the loop above will be optimized away. 1884 1885The use of @cite{Assume_No_Invalid_Values (On)} is appropriate if 1886you know your code is free of uninitialized variables and other 1887possible sources of invalid representations, and may result in 1888more efficient code. A program that accesses an invalid representation 1889with this pragma in effect is erroneous, so no guarantees can be made 1890about its behavior. 1891 1892It is peculiar though permissible to use this pragma in conjunction 1893with validity checking (-gnatVa). In such cases, accessing invalid 1894values will generally give an exception, though formally the program 1895is erroneous so there are no guarantees that this will always be the 1896case, and it is recommended that these two options not be used together. 1897 1898@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 1899@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2a} 1900@section Pragma Async_Readers 1901 1902 1903Syntax: 1904 1905@example 1906pragma Asynch_Readers [ (boolean_EXPRESSION) ]; 1907@end example 1908 1909For the semantics of this pragma, see the entry for aspect @cite{Async_Readers} in 1910the SPARK 2014 Reference Manual, section 7.1.2. 1911 1912@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 1913@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{2b} 1914@section Pragma Async_Writers 1915 1916 1917Syntax: 1918 1919@example 1920pragma Asynch_Writers [ (boolean_EXPRESSION) ]; 1921@end example 1922 1923For the semantics of this pragma, see the entry for aspect @cite{Async_Writers} in 1924the SPARK 2014 Reference Manual, section 7.1.2. 1925 1926@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 1927@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{2c} 1928@section Pragma Attribute_Definition 1929 1930 1931Syntax: 1932 1933@example 1934pragma Attribute_Definition 1935 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 1936 [Entity =>] LOCAL_NAME, 1937 [Expression =>] EXPRESSION | NAME); 1938@end example 1939 1940If @cite{Attribute} is a known attribute name, this pragma is equivalent to 1941the attribute definition clause: 1942 1943@example 1944for Entity'Attribute use Expression; 1945@end example 1946 1947If @cite{Attribute} is not a recognized attribute name, the pragma is 1948ignored, and a warning is emitted. This allows source 1949code to be written that takes advantage of some new attribute, while remaining 1950compilable with earlier compilers. 1951 1952@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 1953@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{2d} 1954@section Pragma C_Pass_By_Copy 1955 1956 1957@geindex Passing by copy 1958 1959Syntax: 1960 1961@example 1962pragma C_Pass_By_Copy 1963 ([Max_Size =>] static_integer_EXPRESSION); 1964@end example 1965 1966Normally the default mechanism for passing C convention records to C 1967convention subprograms is to pass them by reference, as suggested by RM 1968B.3(69). Use the configuration pragma @cite{C_Pass_By_Copy} to change 1969this default, by requiring that record formal parameters be passed by 1970copy if all of the following conditions are met: 1971 1972 1973@itemize * 1974 1975@item 1976The size of the record type does not exceed the value specified for 1977@cite{Max_Size}. 1978 1979@item 1980The record type has @cite{Convention C}. 1981 1982@item 1983The formal parameter has this record type, and the subprogram has a 1984foreign (non-Ada) convention. 1985@end itemize 1986 1987If these conditions are met the argument is passed by copy; i.e., in a 1988manner consistent with what C expects if the corresponding formal in the 1989C prototype is a struct (rather than a pointer to a struct). 1990 1991You can also pass records by copy by specifying the convention 1992@cite{C_Pass_By_Copy} for the record type, or by using the extended 1993@cite{Import} and @cite{Export} pragmas, which allow specification of 1994passing mechanisms on a parameter by parameter basis. 1995 1996@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 1997@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{2e} 1998@section Pragma Check 1999 2000 2001@geindex Assertions 2002 2003@geindex Named assertions 2004 2005Syntax: 2006 2007@example 2008pragma Check ( 2009 [Name =>] CHECK_KIND, 2010 [Check =>] Boolean_EXPRESSION 2011 [, [Message =>] string_EXPRESSION] ); 2012 2013CHECK_KIND ::= IDENTIFIER | 2014 Pre'Class | 2015 Post'Class | 2016 Type_Invariant'Class | 2017 Invariant'Class 2018@end example 2019 2020This pragma is similar to the predefined pragma @cite{Assert} except that an 2021extra identifier argument is present. In conjunction with pragma 2022@cite{Check_Policy}, this can be used to define groups of assertions that can 2023be independently controlled. The identifier @cite{Assertion} is special, it 2024refers to the normal set of pragma @cite{Assert} statements. 2025 2026Checks introduced by this pragma are normally deactivated by default. They can 2027be activated either by the command line option @emph{-gnata}, which turns on 2028all checks, or individually controlled using pragma @cite{Check_Policy}. 2029 2030The identifiers @cite{Assertions} and @cite{Statement_Assertions} are not 2031permitted as check kinds, since this would cause confusion with the use 2032of these identifiers in @cite{Assertion_Policy} and @cite{Check_Policy} 2033pragmas, where they are used to refer to sets of assertions. 2034 2035@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2036@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{2f} 2037@section Pragma Check_Float_Overflow 2038 2039 2040@geindex Floating-point overflow 2041 2042Syntax: 2043 2044@example 2045pragma Check_Float_Overflow; 2046@end example 2047 2048In Ada, the predefined floating-point types (@cite{Short_Float}, 2049@cite{Float}, @cite{Long_Float}, @cite{Long_Long_Float}) are 2050defined to be @emph{unconstrained}. This means that even though each 2051has a well-defined base range, an operation that delivers a result 2052outside this base range is not required to raise an exception. 2053This implementation permission accommodates the notion 2054of infinities in IEEE floating-point, and corresponds to the 2055efficient execution mode on most machines. GNAT will not raise 2056overflow exceptions on these machines; instead it will generate 2057infinities and NaN's as defined in the IEEE standard. 2058 2059Generating infinities, although efficient, is not always desirable. 2060Often the preferable approach is to check for overflow, even at the 2061(perhaps considerable) expense of run-time performance. 2062This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 2063range constraints -- and indeed such a subtype 2064can have the same base range as its base type. For example: 2065 2066@example 2067subtype My_Float is Float range Float'Range; 2068@end example 2069 2070Here @cite{My_Float} has the same range as 2071@cite{Float} but is constrained, so operations on 2072@cite{My_Float} values will be checked for overflow 2073against this range. 2074 2075This style will achieve the desired goal, but 2076it is often more convenient to be able to simply use 2077the standard predefined floating-point types as long 2078as overflow checking could be guaranteed. 2079The @cite{Check_Float_Overflow} 2080configuration pragma achieves this effect. If a unit is compiled 2081subject to this configuration pragma, then all operations 2082on predefined floating-point types including operations on 2083base types of these floating-point types will be treated as 2084though those types were constrained, and overflow checks 2085will be generated. The @cite{Constraint_Error} 2086exception is raised if the result is out of range. 2087 2088This mode can also be set by use of the compiler 2089switch @emph{-gnateF}. 2090 2091@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2092@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{30} 2093@section Pragma Check_Name 2094 2095 2096@geindex Defining check names 2097 2098@geindex Check names 2099@geindex defining 2100 2101Syntax: 2102 2103@example 2104pragma Check_Name (check_name_IDENTIFIER); 2105@end example 2106 2107This is a configuration pragma that defines a new implementation 2108defined check name (unless IDENTIFIER matches one of the predefined 2109check names, in which case the pragma has no effect). Check names 2110are global to a partition, so if two or more configuration pragmas 2111are present in a partition mentioning the same name, only one new 2112check name is introduced. 2113 2114An implementation defined check name introduced with this pragma may 2115be used in only three contexts: @cite{pragma Suppress}, 2116@cite{pragma Unsuppress}, 2117and as the prefix of a @cite{Check_Name'Enabled} attribute reference. For 2118any of these three cases, the check name must be visible. A check 2119name is visible if it is in the configuration pragmas applying to 2120the current unit, or if it appears at the start of any unit that 2121is part of the dependency set of the current unit (e.g., units that 2122are mentioned in @cite{with} clauses). 2123 2124Check names introduced by this pragma are subject to control by compiler 2125switches (in particular -gnatp) in the usual manner. 2126 2127@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2128@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{31} 2129@section Pragma Check_Policy 2130 2131 2132@geindex Controlling assertions 2133 2134@geindex Assertions 2135@geindex control 2136 2137@geindex Check pragma control 2138 2139@geindex Named assertions 2140 2141Syntax: 2142 2143@example 2144pragma Check_Policy 2145 ([Name =>] CHECK_KIND, 2146 [Policy =>] POLICY_IDENTIFIER); 2147 2148pragma Check_Policy ( 2149 CHECK_KIND => POLICY_IDENTIFIER 2150 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2151 2152ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2153 2154CHECK_KIND ::= IDENTIFIER | 2155 Pre'Class | 2156 Post'Class | 2157 Type_Invariant'Class | 2158 Invariant'Class 2159 2160The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2161avoids confusion between the two possible syntax forms for this pragma. 2162 2163POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2164@end example 2165 2166This pragma is used to set the checking policy for assertions (specified 2167by aspects or pragmas), the @cite{Debug} pragma, or additional checks 2168to be checked using the @cite{Check} pragma. It may appear either as 2169a configuration pragma, or within a declarative part of package. In the 2170latter case, it applies from the point where it appears to the end of 2171the declarative region (like pragma @cite{Suppress}). 2172 2173The @cite{Check_Policy} pragma is similar to the 2174predefined @cite{Assertion_Policy} pragma, 2175and if the check kind corresponds to one of the assertion kinds that 2176are allowed by @cite{Assertion_Policy}, then the effect is identical. 2177 2178If the first argument is Debug, then the policy applies to Debug pragmas, 2179disabling their effect if the policy is @cite{OFF}, @cite{DISABLE}, or 2180@cite{IGNORE}, and allowing them to execute with normal semantics if 2181the policy is @cite{ON} or @cite{CHECK}. In addition if the policy is 2182@cite{DISABLE}, then the procedure call in @cite{Debug} pragmas will 2183be totally ignored and not analyzed semantically. 2184 2185Finally the first argument may be some other identifier than the above 2186possibilities, in which case it controls a set of named assertions 2187that can be checked using pragma @cite{Check}. For example, if the pragma: 2188 2189@example 2190pragma Check_Policy (Critical_Error, OFF); 2191@end example 2192 2193is given, then subsequent @cite{Check} pragmas whose first argument is also 2194@cite{Critical_Error} will be disabled. 2195 2196The check policy is @cite{OFF} to turn off corresponding checks, and @cite{ON} 2197to turn on corresponding checks. The default for a set of checks for which no 2198@cite{Check_Policy} is given is @cite{OFF} unless the compiler switch 2199@emph{-gnata} is given, which turns on all checks by default. 2200 2201The check policy settings @cite{CHECK} and @cite{IGNORE} are recognized 2202as synonyms for @cite{ON} and @cite{OFF}. These synonyms are provided for 2203compatibility with the standard @cite{Assertion_Policy} pragma. The check 2204policy setting @cite{DISABLE} causes the second argument of a corresponding 2205@cite{Check} pragma to be completely ignored and not analyzed. 2206 2207@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2208@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{32} 2209@section Pragma Comment 2210 2211 2212Syntax: 2213 2214@example 2215pragma Comment (static_string_EXPRESSION); 2216@end example 2217 2218This is almost identical in effect to pragma @cite{Ident}. It allows the 2219placement of a comment into the object file and hence into the 2220executable file if the operating system permits such usage. The 2221difference is that @cite{Comment}, unlike @cite{Ident}, has 2222no limitations on placement of the pragma (it can be placed 2223anywhere in the main source unit), and if more than one pragma 2224is used, all comments are retained. 2225 2226@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2227@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{33} 2228@section Pragma Common_Object 2229 2230 2231Syntax: 2232 2233@example 2234pragma Common_Object ( 2235 [Internal =>] LOCAL_NAME 2236 [, [External =>] EXTERNAL_SYMBOL] 2237 [, [Size =>] EXTERNAL_SYMBOL] ); 2238 2239EXTERNAL_SYMBOL ::= 2240 IDENTIFIER 2241| static_string_EXPRESSION 2242@end example 2243 2244This pragma enables the shared use of variables stored in overlaid 2245linker areas corresponding to the use of @cite{COMMON} 2246in Fortran. The single 2247object @cite{LOCAL_NAME} is assigned to the area designated by 2248the @cite{External} argument. 2249You may define a record to correspond to a series 2250of fields. The @cite{Size} argument 2251is syntax checked in GNAT, but otherwise ignored. 2252 2253@cite{Common_Object} is not supported on all platforms. If no 2254support is available, then the code generator will issue a message 2255indicating that the necessary attribute for implementation of this 2256pragma is not available. 2257 2258@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2259@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{34} 2260@section Pragma Compile_Time_Error 2261 2262 2263Syntax: 2264 2265@example 2266pragma Compile_Time_Error 2267 (boolean_EXPRESSION, static_string_EXPRESSION); 2268@end example 2269 2270This pragma can be used to generate additional compile time 2271error messages. It 2272is particularly useful in generics, where errors can be issued for 2273specific problematic instantiations. The first parameter is a boolean 2274expression. The pragma is effective only if the value of this expression 2275is known at compile time, and has the value True. The set of expressions 2276whose values are known at compile time includes all static boolean 2277expressions, and also other values which the compiler can determine 2278at compile time (e.g., the size of a record type set by an explicit 2279size representation clause, or the value of a variable which was 2280initialized to a constant and is known not to have been modified). 2281If these conditions are met, an error message is generated using 2282the value given as the second argument. This string value may contain 2283embedded ASCII.LF characters to break the message into multiple lines. 2284 2285@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2286@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{35} 2287@section Pragma Compile_Time_Warning 2288 2289 2290Syntax: 2291 2292@example 2293pragma Compile_Time_Warning 2294 (boolean_EXPRESSION, static_string_EXPRESSION); 2295@end example 2296 2297Same as pragma Compile_Time_Error, except a warning is issued instead 2298of an error message. Note that if this pragma is used in a package that 2299is with'ed by a client, the client will get the warning even though it 2300is issued by a with'ed package (normally warnings in with'ed units are 2301suppressed, but this is a special exception to that rule). 2302 2303One typical use is within a generic where compile time known characteristics 2304of formal parameters are tested, and warnings given appropriately. Another use 2305with a first parameter of True is to warn a client about use of a package, 2306for example that it is not fully implemented. 2307 2308@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2309@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{36} 2310@section Pragma Compiler_Unit 2311 2312 2313Syntax: 2314 2315@example 2316pragma Compiler_Unit; 2317@end example 2318 2319This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2320retained so that old versions of the GNAT run-time that use this pragma can 2321be compiled with newer versions of the compiler. 2322 2323@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2324@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{37} 2325@section Pragma Compiler_Unit_Warning 2326 2327 2328Syntax: 2329 2330@example 2331pragma Compiler_Unit_Warning; 2332@end example 2333 2334This pragma is intended only for internal use in the GNAT run-time library. 2335It indicates that the unit is used as part of the compiler build. The effect 2336is to generate warnings for the use of constructs (for example, conditional 2337expressions) that would cause trouble when bootstrapping using an older 2338version of GNAT. For the exact list of restrictions, see the compiler sources 2339and references to Check_Compiler_Unit. 2340 2341@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2342@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{38} 2343@section Pragma Complete_Representation 2344 2345 2346Syntax: 2347 2348@example 2349pragma Complete_Representation; 2350@end example 2351 2352This pragma must appear immediately within a record representation 2353clause. Typical placements are before the first component clause 2354or after the last component clause. The effect is to give an error 2355message if any component is missing a component clause. This pragma 2356may be used to ensure that a record representation clause is 2357complete, and that this invariant is maintained if fields are 2358added to the record in the future. 2359 2360@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2361@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{39} 2362@section Pragma Complex_Representation 2363 2364 2365Syntax: 2366 2367@example 2368pragma Complex_Representation 2369 ([Entity =>] LOCAL_NAME); 2370@end example 2371 2372The @cite{Entity} argument must be the name of a record type which has 2373two fields of the same floating-point type. The effect of this pragma is 2374to force gcc to use the special internal complex representation form for 2375this record, which may be more efficient. Note that this may result in 2376the code for this type not conforming to standard ABI (application 2377binary interface) requirements for the handling of record types. For 2378example, in some environments, there is a requirement for passing 2379records by pointer, and the use of this pragma may result in passing 2380this type in floating-point registers. 2381 2382@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2383@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{3a} 2384@section Pragma Component_Alignment 2385 2386 2387@geindex Alignments of components 2388 2389@geindex Pragma Component_Alignment 2390 2391Syntax: 2392 2393@example 2394pragma Component_Alignment ( 2395 [Form =>] ALIGNMENT_CHOICE 2396 [, [Name =>] type_LOCAL_NAME]); 2397 2398ALIGNMENT_CHOICE ::= 2399 Component_Size 2400| Component_Size_4 2401| Storage_Unit 2402| Default 2403@end example 2404 2405Specifies the alignment of components in array or record types. 2406The meaning of the @cite{Form} argument is as follows: 2407 2408@quotation 2409 2410@geindex Component_Size (in pragma Component_Alignment) 2411@end quotation 2412 2413 2414@table @asis 2415 2416@item @emph{Component_Size} 2417 2418Aligns scalar components and subcomponents of the array or record type 2419on boundaries appropriate to their inherent size (naturally 2420aligned). For example, 1-byte components are aligned on byte boundaries, 24212-byte integer components are aligned on 2-byte boundaries, 4-byte 2422integer components are aligned on 4-byte boundaries and so on. These 2423alignment rules correspond to the normal rules for C compilers on all 2424machines except the VAX. 2425 2426@geindex Component_Size_4 (in pragma Component_Alignment) 2427 2428@item @emph{Component_Size_4} 2429 2430Naturally aligns components with a size of four or fewer 2431bytes. Components that are larger than 4 bytes are placed on the next 24324-byte boundary. 2433 2434@geindex Storage_Unit (in pragma Component_Alignment) 2435 2436@item @emph{Storage_Unit} 2437 2438Specifies that array or record components are byte aligned, i.e., 2439aligned on boundaries determined by the value of the constant 2440@cite{System.Storage_Unit}. 2441 2442@geindex Default (in pragma Component_Alignment) 2443 2444@item @emph{Default} 2445 2446Specifies that array or record components are aligned on default 2447boundaries, appropriate to the underlying hardware or operating system or 2448both. The @cite{Default} choice is the same as @cite{Component_Size} (natural 2449alignment). 2450@end table 2451 2452If the @cite{Name} parameter is present, @cite{type_LOCAL_NAME} must 2453refer to a local record or array type, and the specified alignment 2454choice applies to the specified type. The use of 2455@cite{Component_Alignment} together with a pragma @cite{Pack} causes the 2456@cite{Component_Alignment} pragma to be ignored. The use of 2457@cite{Component_Alignment} together with a record representation clause 2458is only effective for fields not specified by the representation clause. 2459 2460If the @cite{Name} parameter is absent, the pragma can be used as either 2461a configuration pragma, in which case it applies to one or more units in 2462accordance with the normal rules for configuration pragmas, or it can be 2463used within a declarative part, in which case it applies to types that 2464are declared within this declarative part, or within any nested scope 2465within this declarative part. In either case it specifies the alignment 2466to be applied to any record or array type which has otherwise standard 2467representation. 2468 2469If the alignment for a record or array type is not specified (using 2470pragma @cite{Pack}, pragma @cite{Component_Alignment}, or a record rep 2471clause), the GNAT uses the default alignment as described previously. 2472 2473@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2474@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{3b} 2475@section Pragma Constant_After_Elaboration 2476 2477 2478Syntax: 2479 2480@example 2481pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2482@end example 2483 2484For the semantics of this pragma, see the entry for aspect 2485@cite{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2486 2487@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2488@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{3c} 2489@section Pragma Contract_Cases 2490 2491 2492@geindex Contract cases 2493 2494Syntax: 2495 2496@example 2497pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2498 2499CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2500 2501CASE_GUARD ::= boolean_EXPRESSION | others 2502 2503CONSEQUENCE ::= boolean_EXPRESSION 2504@end example 2505 2506The @cite{Contract_Cases} pragma allows defining fine-grain specifications 2507that can complement or replace the contract given by a precondition and a 2508postcondition. Additionally, the @cite{Contract_Cases} pragma can be used 2509by testing and formal verification tools. The compiler checks its validity and, 2510depending on the assertion policy at the point of declaration of the pragma, 2511it may insert a check in the executable. For code generation, the contract 2512cases 2513 2514@example 2515pragma Contract_Cases ( 2516 Cond1 => Pred1, 2517 Cond2 => Pred2); 2518@end example 2519 2520are equivalent to 2521 2522@example 2523C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2524C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2525pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2526pragma Postcondition (if C1 then Pred1); 2527pragma Postcondition (if C2 then Pred2); 2528@end example 2529 2530The precondition ensures that one and only one of the conditions is 2531satisfied on entry to the subprogram. 2532The postcondition ensures that for the condition that was True on entry, 2533the corrresponding consequence is True on exit. Other consequence expressions 2534are not evaluated. 2535 2536A precondition @cite{P} and postcondition @cite{Q} can also be 2537expressed as contract cases: 2538 2539@example 2540pragma Contract_Cases (P => Q); 2541@end example 2542 2543The placement and visibility rules for @cite{Contract_Cases} pragmas are 2544identical to those described for preconditions and postconditions. 2545 2546The compiler checks that boolean expressions given in conditions and 2547consequences are valid, where the rules for conditions are the same as 2548the rule for an expression in @cite{Precondition} and the rules for 2549consequences are the same as the rule for an expression in 2550@cite{Postcondition}. In particular, attributes @cite{'Old} and 2551@cite{'Result} can only be used within consequence expressions. 2552The condition for the last contract case may be @cite{others}, to denote 2553any case not captured by the previous cases. The 2554following is an example of use within a package spec: 2555 2556@example 2557package Math_Functions is 2558 ... 2559 function Sqrt (Arg : Float) return Float; 2560 pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10, 2561 Arg >= 100 => Sqrt'Result >= 10, 2562 others => Sqrt'Result = 0); 2563 ... 2564end Math_Functions; 2565@end example 2566 2567The meaning of contract cases is that only one case should apply at each 2568call, as determined by the corresponding condition evaluating to True, 2569and that the consequence for this case should hold when the subprogram 2570returns. 2571 2572@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2573@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{3d} 2574@section Pragma Convention_Identifier 2575 2576 2577@geindex Conventions 2578@geindex synonyms 2579 2580Syntax: 2581 2582@example 2583pragma Convention_Identifier ( 2584 [Name =>] IDENTIFIER, 2585 [Convention =>] convention_IDENTIFIER); 2586@end example 2587 2588This pragma provides a mechanism for supplying synonyms for existing 2589convention identifiers. The @cite{Name} identifier can subsequently 2590be used as a synonym for the given convention in other pragmas (including 2591for example pragma @cite{Import} or another @cite{Convention_Identifier} 2592pragma). As an example of the use of this, suppose you had legacy code 2593which used Fortran77 as the identifier for Fortran. Then the pragma: 2594 2595@example 2596pragma Convention_Identifier (Fortran77, Fortran); 2597@end example 2598 2599would allow the use of the convention identifier @cite{Fortran77} in 2600subsequent code, avoiding the need to modify the sources. As another 2601example, you could use this to parameterize convention requirements 2602according to systems. Suppose you needed to use @cite{Stdcall} on 2603windows systems, and @cite{C} on some other system, then you could 2604define a convention identifier @cite{Library} and use a single 2605@cite{Convention_Identifier} pragma to specify which convention 2606would be used system-wide. 2607 2608@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2609@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{3e} 2610@section Pragma CPP_Class 2611 2612 2613@geindex Interfacing with C++ 2614 2615Syntax: 2616 2617@example 2618pragma CPP_Class ([Entity =>] LOCAL_NAME); 2619@end example 2620 2621The argument denotes an entity in the current declarative region that is 2622declared as a record type. It indicates that the type corresponds to an 2623externally declared C++ class type, and is to be laid out the same way 2624that C++ would lay out the type. If the C++ class has virtual primitives 2625then the record must be declared as a tagged record type. 2626 2627Types for which @cite{CPP_Class} is specified do not have assignment or 2628equality operators defined (such operations can be imported or declared 2629as subprograms as required). Initialization is allowed only by constructor 2630functions (see pragma @cite{CPP_Constructor}). Such types are implicitly 2631limited if not explicitly declared as limited or derived from a limited 2632type, and an error is issued in that case. 2633 2634See @ref{3f,,Interfacing to C++} for related information. 2635 2636Note: Pragma @cite{CPP_Class} is currently obsolete. It is supported 2637for backward compatibility but its functionality is available 2638using pragma @cite{Import} with @cite{Convention} = @cite{CPP}. 2639 2640@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2641@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{40} 2642@section Pragma CPP_Constructor 2643 2644 2645@geindex Interfacing with C++ 2646 2647Syntax: 2648 2649@example 2650pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2651 [, [External_Name =>] static_string_EXPRESSION ] 2652 [, [Link_Name =>] static_string_EXPRESSION ]); 2653@end example 2654 2655This pragma identifies an imported function (imported in the usual way 2656with pragma @cite{Import}) as corresponding to a C++ constructor. If 2657@cite{External_Name} and @cite{Link_Name} are not specified then the 2658@cite{Entity} argument is a name that must have been previously mentioned 2659in a pragma @cite{Import} with @cite{Convention} = @cite{CPP}. Such name 2660must be of one of the following forms: 2661 2662 2663@itemize * 2664 2665@item 2666@strong{function} @cite{Fname} @strong{return} T` 2667 2668@item 2669@strong{function} @cite{Fname} @strong{return} T'Class 2670 2671@item 2672@strong{function} @cite{Fname} (...) @strong{return} T` 2673 2674@item 2675@strong{function} @cite{Fname} (...) @strong{return} T'Class 2676@end itemize 2677 2678where @cite{T} is a limited record type imported from C++ with pragma 2679@cite{Import} and @cite{Convention} = @cite{CPP}. 2680 2681The first two forms import the default constructor, used when an object 2682of type @cite{T} is created on the Ada side with no explicit constructor. 2683The latter two forms cover all the non-default constructors of the type. 2684See the GNAT User's Guide for details. 2685 2686If no constructors are imported, it is impossible to create any objects 2687on the Ada side and the type is implicitly declared abstract. 2688 2689Pragma @cite{CPP_Constructor} is intended primarily for automatic generation 2690using an automatic binding generator tool (such as the @cite{-fdump-ada-spec} 2691GCC switch). 2692See @ref{3f,,Interfacing to C++} for more related information. 2693 2694Note: The use of functions returning class-wide types for constructors is 2695currently obsolete. They are supported for backward compatibility. The 2696use of functions returning the type T leave the Ada sources more clear 2697because the imported C++ constructors always return an object of type T; 2698that is, they never return an object whose type is a descendant of type T. 2699 2700@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2701@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{41} 2702@section Pragma CPP_Virtual 2703 2704 2705@geindex Interfacing to C++ 2706 2707This pragma is now obsolete and, other than generating a warning if warnings 2708on obsolescent features are enabled, is completely ignored. 2709It is retained for compatibility 2710purposes. It used to be required to ensure compoatibility with C++, but 2711is no longer required for that purpose because GNAT generates 2712the same object layout as the G++ compiler by default. 2713 2714See @ref{3f,,Interfacing to C++} for related information. 2715 2716@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2717@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{42} 2718@section Pragma CPP_Vtable 2719 2720 2721@geindex Interfacing with C++ 2722 2723This pragma is now obsolete and, other than generating a warning if warnings 2724on obsolescent features are enabled, is completely ignored. 2725It used to be required to ensure compatibility with C++, but 2726is no longer required for that purpose because GNAT generates 2727the same object layout as the G++ compiler by default. 2728 2729See @ref{3f,,Interfacing to C++} for related information. 2730 2731@node Pragma CPU,Pragma Default_Initial_Condition,Pragma CPP_Vtable,Implementation Defined Pragmas 2732@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{43} 2733@section Pragma CPU 2734 2735 2736Syntax: 2737 2738@example 2739pragma CPU (EXPRESSION); 2740@end example 2741 2742This pragma is standard in Ada 2012, but is available in all earlier 2743versions of Ada as an implementation-defined pragma. 2744See Ada 2012 Reference Manual for details. 2745 2746@node Pragma Default_Initial_Condition,Pragma Debug,Pragma CPU,Implementation Defined Pragmas 2747@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{44} 2748@section Pragma Default_Initial_Condition 2749 2750 2751Syntax: 2752 2753@example 2754pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2755@end example 2756 2757For the semantics of this pragma, see the entry for aspect 2758@cite{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2759 2760@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2761@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{45} 2762@section Pragma Debug 2763 2764 2765Syntax: 2766 2767@example 2768pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2769 2770PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2771 PROCEDURE_NAME 2772| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2773@end example 2774 2775The procedure call argument has the syntactic form of an expression, meeting 2776the syntactic requirements for pragmas. 2777 2778If debug pragmas are not enabled or if the condition is present and evaluates 2779to False, this pragma has no effect. If debug pragmas are enabled, the 2780semantics of the pragma is exactly equivalent to the procedure call statement 2781corresponding to the argument with a terminating semicolon. Pragmas are 2782permitted in sequences of declarations, so you can use pragma @cite{Debug} to 2783intersperse calls to debug procedures in the middle of declarations. Debug 2784pragmas can be enabled either by use of the command line switch @emph{-gnata} 2785or by use of the pragma @cite{Check_Policy} with a first argument of 2786@cite{Debug}. 2787 2788@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 2789@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{46} 2790@section Pragma Debug_Policy 2791 2792 2793Syntax: 2794 2795@example 2796pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 2797@end example 2798 2799This pragma is equivalent to a corresponding @cite{Check_Policy} pragma 2800with a first argument of @cite{Debug}. It is retained for historical 2801compatibility reasons. 2802 2803@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 2804@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{47} 2805@section Pragma Default_Scalar_Storage_Order 2806 2807 2808@geindex Default_Scalar_Storage_Order 2809 2810@geindex Scalar_Storage_Order 2811 2812Syntax: 2813 2814@example 2815pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 2816@end example 2817 2818Normally if no explicit @cite{Scalar_Storage_Order} is given for a record 2819type or array type, then the scalar storage order defaults to the ordinary 2820default for the target. But this default may be overridden using this pragma. 2821The pragma may appear as a configuration pragma, or locally within a package 2822spec or declarative part. In the latter case, it applies to all subsequent 2823types declared within that package spec or declarative part. 2824 2825The following example shows the use of this pragma: 2826 2827@example 2828pragma Default_Scalar_Storage_Order (High_Order_First); 2829with System; use System; 2830package DSSO1 is 2831 type H1 is record 2832 a : Integer; 2833 end record; 2834 2835 type L2 is record 2836 a : Integer; 2837 end record; 2838 for L2'Scalar_Storage_Order use Low_Order_First; 2839 2840 type L2a is new L2; 2841 2842 package Inner is 2843 type H3 is record 2844 a : Integer; 2845 end record; 2846 2847 pragma Default_Scalar_Storage_Order (Low_Order_First); 2848 2849 type L4 is record 2850 a : Integer; 2851 end record; 2852 end Inner; 2853 2854 type H4a is new Inner.L4; 2855 2856 type H5 is record 2857 a : Integer; 2858 end record; 2859end DSSO1; 2860@end example 2861 2862In this example record types L.. have @cite{Low_Order_First} scalar 2863storage order, and record types H.. have @cite{High_Order_First}. 2864Note that in the case of @cite{H4a}, the order is not inherited 2865from the parent type. Only an explicitly set @cite{Scalar_Storage_Order} 2866gets inherited on type derivation. 2867 2868If this pragma is used as a configuration pragma which appears within a 2869configuration pragma file (as opposed to appearing explicitly at the start 2870of a single unit), then the binder will require that all units in a partition 2871be compiled in a similar manner, other than run-time units, which are not 2872affected by this pragma. Note that the use of this form is discouraged because 2873it may significantly degrade the run-time performance of the software, instead 2874the default scalar storage order ought to be changed only on a local basis. 2875 2876@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 2877@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{48} 2878@section Pragma Default_Storage_Pool 2879 2880 2881@geindex Default_Storage_Pool 2882 2883Syntax: 2884 2885@example 2886pragma Default_Storage_Pool (storage_pool_NAME | null); 2887@end example 2888 2889This pragma is standard in Ada 2012, but is available in all earlier 2890versions of Ada as an implementation-defined pragma. 2891See Ada 2012 Reference Manual for details. 2892 2893@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 2894@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{49} 2895@section Pragma Depends 2896 2897 2898Syntax: 2899 2900@example 2901pragma Depends (DEPENDENCY_RELATION); 2902 2903DEPENDENCY_RELATION ::= 2904 null 2905 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 2906 2907DEPENDENCY_CLAUSE ::= 2908 OUTPUT_LIST =>[+] INPUT_LIST 2909 | NULL_DEPENDENCY_CLAUSE 2910 2911NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 2912 2913OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 2914 2915INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 2916 2917OUTPUT ::= NAME | FUNCTION_RESULT 2918INPUT ::= NAME 2919 2920where FUNCTION_RESULT is a function Result attribute_reference 2921@end example 2922 2923For the semantics of this pragma, see the entry for aspect @cite{Depends} in the 2924SPARK 2014 Reference Manual, section 6.1.5. 2925 2926@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 2927@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{4a} 2928@section Pragma Detect_Blocking 2929 2930 2931Syntax: 2932 2933@example 2934pragma Detect_Blocking; 2935@end example 2936 2937This is a standard pragma in Ada 2005, that is available in all earlier 2938versions of Ada as an implementation-defined pragma. 2939 2940This is a configuration pragma that forces the detection of potentially 2941blocking operations within a protected operation, and to raise Program_Error 2942if that happens. 2943 2944@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 2945@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{4b} 2946@section Pragma Disable_Atomic_Synchronization 2947 2948 2949@geindex Atomic Synchronization 2950 2951Syntax: 2952 2953@example 2954pragma Disable_Atomic_Synchronization [(Entity)]; 2955@end example 2956 2957Ada requires that accesses (reads or writes) of an atomic variable be 2958regarded as synchronization points in the case of multiple tasks. 2959Particularly in the case of multi-processors this may require special 2960handling, e.g. the generation of memory barriers. This capability may 2961be turned off using this pragma in cases where it is known not to be 2962required. 2963 2964The placement and scope rules for this pragma are the same as those 2965for @cite{pragma Suppress}. In particular it can be used as a 2966configuration pragma, or in a declaration sequence where it applies 2967till the end of the scope. If an @cite{Entity} argument is present, 2968the action applies only to that entity. 2969 2970@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 2971@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{4c} 2972@section Pragma Dispatching_Domain 2973 2974 2975Syntax: 2976 2977@example 2978pragma Dispatching_Domain (EXPRESSION); 2979@end example 2980 2981This pragma is standard in Ada 2012, but is available in all earlier 2982versions of Ada as an implementation-defined pragma. 2983See Ada 2012 Reference Manual for details. 2984 2985@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 2986@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{4d} 2987@section Pragma Effective_Reads 2988 2989 2990Syntax: 2991 2992@example 2993pragma Effective_Reads [ (boolean_EXPRESSION) ]; 2994@end example 2995 2996For the semantics of this pragma, see the entry for aspect @cite{Effective_Reads} in 2997the SPARK 2014 Reference Manual, section 7.1.2. 2998 2999@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3000@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{4e} 3001@section Pragma Effective_Writes 3002 3003 3004Syntax: 3005 3006@example 3007pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3008@end example 3009 3010For the semantics of this pragma, see the entry for aspect @cite{Effective_Writes} 3011in the SPARK 2014 Reference Manual, section 7.1.2. 3012 3013@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3014@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{4f} 3015@section Pragma Elaboration_Checks 3016 3017 3018@geindex Elaboration control 3019 3020Syntax: 3021 3022@example 3023pragma Elaboration_Checks (Dynamic | Static); 3024@end example 3025 3026This is a configuration pragma that provides control over the 3027elaboration model used by the compilation affected by the 3028pragma. If the parameter is @cite{Dynamic}, 3029then the dynamic elaboration 3030model described in the Ada Reference Manual is used, as though 3031the @emph{-gnatE} switch had been specified on the command 3032line. If the parameter is @cite{Static}, then the default GNAT static 3033model is used. This configuration pragma overrides the setting 3034of the command line. For full details on the elaboration models 3035used by the GNAT compiler, see the chapter on elaboration order handling 3036in the @emph{GNAT User's Guide}. 3037 3038@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3039@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{50} 3040@section Pragma Eliminate 3041 3042 3043@geindex Elimination of unused subprograms 3044 3045Syntax: 3046 3047@example 3048pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR, 3049 [Source_Location =>] STRING_LITERAL); 3050@end example 3051 3052The string literal given for the source location is a string which 3053specifies the line number of the occurrence of the entity, using 3054the syntax for SOURCE_TRACE given below: 3055 3056@example 3057SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET] 3058 3059LBRACKET ::= [ 3060RBRACKET ::= ] 3061 3062SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3063 3064LINE_NUMBER ::= DIGIT @{DIGIT@} 3065@end example 3066 3067Spaces around the colon in a @cite{Source_Reference} are optional. 3068 3069The @cite{DEFINING_DESIGNATOR} matches the defining designator used in an 3070explicit subprogram declaration, where the @cite{entity} name in this 3071designator appears on the source line specified by the source location. 3072 3073The source trace that is given as the @cite{Source_Location} shall obey the 3074following rules. The @cite{FILE_NAME} is the short name (with no directory 3075information) of an Ada source file, given using exactly the required syntax 3076for the underlying file system (e.g. case is important if the underlying 3077operating system is case sensitive). @cite{LINE_NUMBER} gives the line 3078number of the occurrence of the @cite{entity} 3079as a decimal literal without an exponent or point. If an @cite{entity} is not 3080declared in a generic instantiation (this includes generic subprogram 3081instances), the source trace includes only one source reference. If an entity 3082is declared inside a generic instantiation, its source trace (when parsing 3083from left to right) starts with the source location of the declaration of the 3084entity in the generic unit and ends with the source location of the 3085instantiation (it is given in square brackets). This approach is recursively 3086used in case of nested instantiations: the rightmost (nested most deeply in 3087square brackets) element of the source trace is the location of the outermost 3088instantiation, the next to left element is the location of the next (first 3089nested) instantiation in the code of the corresponding generic unit, and so 3090on, and the leftmost element (that is out of any square brackets) is the 3091location of the declaration of the entity to eliminate in a generic unit. 3092 3093Note that the @cite{Source_Location} argument specifies which of a set of 3094similarly named entities is being eliminated, dealing both with overloading, 3095and also appearance of the same entity name in different scopes. 3096 3097This pragma indicates that the given entity is not used in the program to be 3098compiled and built. The effect of the pragma is to allow the compiler to 3099eliminate the code or data associated with the named entity. Any reference to 3100an eliminated entity causes a compile-time or link-time error. 3101 3102The intention of pragma @cite{Eliminate} is to allow a program to be compiled 3103in a system-independent manner, with unused entities eliminated, without 3104needing to modify the source text. Normally the required set of 3105@cite{Eliminate} pragmas is constructed automatically using the gnatelim tool. 3106 3107Any source file change that removes, splits, or 3108adds lines may make the set of Eliminate pragmas invalid because their 3109@cite{Source_Location} argument values may get out of date. 3110 3111Pragma @cite{Eliminate} may be used where the referenced entity is a dispatching 3112operation. In this case all the subprograms to which the given operation can 3113dispatch are considered to be unused (are never called as a result of a direct 3114or a dispatching call). 3115 3116@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3117@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{51} 3118@section Pragma Enable_Atomic_Synchronization 3119 3120 3121@geindex Atomic Synchronization 3122 3123Syntax: 3124 3125@example 3126pragma Enable_Atomic_Synchronization [(Entity)]; 3127@end example 3128 3129Ada requires that accesses (reads or writes) of an atomic variable be 3130regarded as synchronization points in the case of multiple tasks. 3131Particularly in the case of multi-processors this may require special 3132handling, e.g. the generation of memory barriers. This synchronization 3133is performed by default, but can be turned off using 3134@cite{pragma Disable_Atomic_Synchronization}. The 3135@cite{Enable_Atomic_Synchronization} pragma can be used to turn 3136it back on. 3137 3138The placement and scope rules for this pragma are the same as those 3139for @cite{pragma Unsuppress}. In particular it can be used as a 3140configuration pragma, or in a declaration sequence where it applies 3141till the end of the scope. If an @cite{Entity} argument is present, 3142the action applies only to that entity. 3143 3144@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3145@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{52} 3146@section Pragma Export_Function 3147 3148 3149@geindex Argument passing mechanisms 3150 3151Syntax: 3152 3153@example 3154pragma Export_Function ( 3155 [Internal =>] LOCAL_NAME 3156 [, [External =>] EXTERNAL_SYMBOL] 3157 [, [Parameter_Types =>] PARAMETER_TYPES] 3158 [, [Result_Type =>] result_SUBTYPE_MARK] 3159 [, [Mechanism =>] MECHANISM] 3160 [, [Result_Mechanism =>] MECHANISM_NAME]); 3161 3162EXTERNAL_SYMBOL ::= 3163 IDENTIFIER 3164| static_string_EXPRESSION 3165| "" 3166 3167PARAMETER_TYPES ::= 3168 null 3169| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3170 3171TYPE_DESIGNATOR ::= 3172 subtype_NAME 3173| subtype_Name ' Access 3174 3175MECHANISM ::= 3176 MECHANISM_NAME 3177| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3178 3179MECHANISM_ASSOCIATION ::= 3180 [formal_parameter_NAME =>] MECHANISM_NAME 3181 3182MECHANISM_NAME ::= Value | Reference 3183@end example 3184 3185Use this pragma to make a function externally callable and optionally 3186provide information on mechanisms to be used for passing parameter and 3187result values. We recommend, for the purposes of improving portability, 3188this pragma always be used in conjunction with a separate pragma 3189@cite{Export}, which must precede the pragma @cite{Export_Function}. 3190GNAT does not require a separate pragma @cite{Export}, but if none is 3191present, @cite{Convention Ada} is assumed, which is usually 3192not what is wanted, so it is usually appropriate to use this 3193pragma in conjunction with a @cite{Export} or @cite{Convention} 3194pragma that specifies the desired foreign convention. 3195Pragma @cite{Export_Function} 3196(and @cite{Export}, if present) must appear in the same declarative 3197region as the function to which they apply. 3198 3199@cite{internal_name} must uniquely designate the function to which the 3200pragma applies. If more than one function name exists of this name in 3201the declarative part you must use the @cite{Parameter_Types} and 3202@cite{Result_Type} parameters is mandatory to achieve the required 3203unique designation. @cite{subtype_mark`s in these parameters must exactly match the subtypes in the corresponding function specification@comma{} using positional notation to match parameters with subtype marks. The form with an `'Access} attribute can be used to match an 3204anonymous access parameter. 3205 3206@geindex Suppressing external name 3207 3208Special treatment is given if the EXTERNAL is an explicit null 3209string or a static string expressions that evaluates to the null 3210string. In this case, no external name is generated. This form 3211still allows the specification of parameter mechanisms. 3212 3213@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3214@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{53} 3215@section Pragma Export_Object 3216 3217 3218Syntax: 3219 3220@example 3221pragma Export_Object 3222 [Internal =>] LOCAL_NAME 3223 [, [External =>] EXTERNAL_SYMBOL] 3224 [, [Size =>] EXTERNAL_SYMBOL] 3225 3226EXTERNAL_SYMBOL ::= 3227 IDENTIFIER 3228| static_string_EXPRESSION 3229@end example 3230 3231This pragma designates an object as exported, and apart from the 3232extended rules for external symbols, is identical in effect to the use of 3233the normal @cite{Export} pragma applied to an object. You may use a 3234separate Export pragma (and you probably should from the point of view 3235of portability), but it is not required. @cite{Size} is syntax checked, 3236but otherwise ignored by GNAT. 3237 3238@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas 3239@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{54} 3240@section Pragma Export_Procedure 3241 3242 3243Syntax: 3244 3245@example 3246pragma Export_Procedure ( 3247 [Internal =>] LOCAL_NAME 3248 [, [External =>] EXTERNAL_SYMBOL] 3249 [, [Parameter_Types =>] PARAMETER_TYPES] 3250 [, [Mechanism =>] MECHANISM]); 3251 3252EXTERNAL_SYMBOL ::= 3253 IDENTIFIER 3254| static_string_EXPRESSION 3255| "" 3256 3257PARAMETER_TYPES ::= 3258 null 3259| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3260 3261TYPE_DESIGNATOR ::= 3262 subtype_NAME 3263| subtype_Name ' Access 3264 3265MECHANISM ::= 3266 MECHANISM_NAME 3267| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3268 3269MECHANISM_ASSOCIATION ::= 3270 [formal_parameter_NAME =>] MECHANISM_NAME 3271 3272MECHANISM_NAME ::= Value | Reference 3273@end example 3274 3275This pragma is identical to @cite{Export_Function} except that it 3276applies to a procedure rather than a function and the parameters 3277@cite{Result_Type} and @cite{Result_Mechanism} are not permitted. 3278GNAT does not require a separate pragma @cite{Export}, but if none is 3279present, @cite{Convention Ada} is assumed, which is usually 3280not what is wanted, so it is usually appropriate to use this 3281pragma in conjunction with a @cite{Export} or @cite{Convention} 3282pragma that specifies the desired foreign convention. 3283 3284@geindex Suppressing external name 3285 3286Special treatment is given if the EXTERNAL is an explicit null 3287string or a static string expressions that evaluates to the null 3288string. In this case, no external name is generated. This form 3289still allows the specification of parameter mechanisms. 3290 3291@node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas 3292@anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{55} 3293@section Pragma Export_Value 3294 3295 3296Syntax: 3297 3298@example 3299pragma Export_Value ( 3300 [Value =>] static_integer_EXPRESSION, 3301 [Link_Name =>] static_string_EXPRESSION); 3302@end example 3303 3304This pragma serves to export a static integer value for external use. 3305The first argument specifies the value to be exported. The Link_Name 3306argument specifies the symbolic name to be associated with the integer 3307value. This pragma is useful for defining a named static value in Ada 3308that can be referenced in assembly language units to be linked with 3309the application. This pragma is currently supported only for the 3310AAMP target and is ignored for other targets. 3311 3312@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas 3313@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{56} 3314@section Pragma Export_Valued_Procedure 3315 3316 3317Syntax: 3318 3319@example 3320pragma Export_Valued_Procedure ( 3321 [Internal =>] LOCAL_NAME 3322 [, [External =>] EXTERNAL_SYMBOL] 3323 [, [Parameter_Types =>] PARAMETER_TYPES] 3324 [, [Mechanism =>] MECHANISM]); 3325 3326EXTERNAL_SYMBOL ::= 3327 IDENTIFIER 3328| static_string_EXPRESSION 3329| "" 3330 3331PARAMETER_TYPES ::= 3332 null 3333| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3334 3335TYPE_DESIGNATOR ::= 3336 subtype_NAME 3337| subtype_Name ' Access 3338 3339MECHANISM ::= 3340 MECHANISM_NAME 3341| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3342 3343MECHANISM_ASSOCIATION ::= 3344 [formal_parameter_NAME =>] MECHANISM_NAME 3345 3346MECHANISM_NAME ::= Value | Reference 3347@end example 3348 3349This pragma is identical to @cite{Export_Procedure} except that the 3350first parameter of @cite{LOCAL_NAME}, which must be present, must be of 3351mode @cite{OUT}, and externally the subprogram is treated as a function 3352with this parameter as the result of the function. GNAT provides for 3353this capability to allow the use of @cite{OUT} and @cite{IN OUT} 3354parameters in interfacing to external functions (which are not permitted 3355in Ada functions). 3356GNAT does not require a separate pragma @cite{Export}, but if none is 3357present, @cite{Convention Ada} is assumed, which is almost certainly 3358not what is wanted since the whole point of this pragma is to interface 3359with foreign language functions, so it is usually appropriate to use this 3360pragma in conjunction with a @cite{Export} or @cite{Convention} 3361pragma that specifies the desired foreign convention. 3362 3363@geindex Suppressing external name 3364 3365Special treatment is given if the EXTERNAL is an explicit null 3366string or a static string expressions that evaluates to the null 3367string. In this case, no external name is generated. This form 3368still allows the specification of parameter mechanisms. 3369 3370@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3371@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{57} 3372@section Pragma Extend_System 3373 3374 3375@geindex System 3376@geindex extending 3377 3378@geindex DEC Ada 83 3379 3380Syntax: 3381 3382@example 3383pragma Extend_System ([Name =>] IDENTIFIER); 3384@end example 3385 3386This pragma is used to provide backwards compatibility with other 3387implementations that extend the facilities of package @cite{System}. In 3388GNAT, @cite{System} contains only the definitions that are present in 3389the Ada RM. However, other implementations, notably the DEC Ada 83 3390implementation, provide many extensions to package @cite{System}. 3391 3392For each such implementation accommodated by this pragma, GNAT provides a 3393package @cite{Aux_`xxx`}, e.g., @cite{Aux_DEC} for the DEC Ada 83 3394implementation, which provides the required additional definitions. You 3395can use this package in two ways. You can @cite{with} it in the normal 3396way and access entities either by selection or using a @cite{use} 3397clause. In this case no special processing is required. 3398 3399However, if existing code contains references such as 3400@cite{System.`xxx`} where @cite{xxx} is an entity in the extended 3401definitions provided in package @cite{System}, you may use this pragma 3402to extend visibility in @cite{System} in a non-standard way that 3403provides greater compatibility with the existing code. Pragma 3404@cite{Extend_System} is a configuration pragma whose single argument is 3405the name of the package containing the extended definition 3406(e.g., @cite{Aux_DEC} for the DEC Ada case). A unit compiled under 3407control of this pragma will be processed using special visibility 3408processing that looks in package @cite{System.Aux_`xxx`} where 3409@cite{Aux_`xxx`} is the pragma argument for any entity referenced in 3410package @cite{System}, but not found in package @cite{System}. 3411 3412You can use this pragma either to access a predefined @cite{System} 3413extension supplied with the compiler, for example @cite{Aux_DEC} or 3414you can construct your own extension unit following the above 3415definition. Note that such a package is a child of @cite{System} 3416and thus is considered part of the implementation. 3417To compile it you will have to use the @emph{-gnatg} switch 3418for compiling System units, as explained in the 3419GNAT User's Guide. 3420 3421@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3422@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{58} 3423@section Pragma Extensions_Allowed 3424 3425 3426@geindex Ada Extensions 3427 3428@geindex GNAT Extensions 3429 3430Syntax: 3431 3432@example 3433pragma Extensions_Allowed (On | Off); 3434@end example 3435 3436This configuration pragma enables or disables the implementation 3437extension mode (the use of Off as a parameter cancels the effect 3438of the @emph{-gnatX} command switch). 3439 3440In extension mode, the latest version of the Ada language is 3441implemented (currently Ada 2012), and in addition a small number 3442of GNAT specific extensions are recognized as follows: 3443 3444 3445@table @asis 3446 3447@item @emph{Constrained attribute for generic objects} 3448 3449The @cite{Constrained} attribute is permitted for objects of 3450generic types. The result indicates if the corresponding actual 3451is constrained. 3452@end table 3453 3454@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3455@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{59} 3456@section Pragma Extensions_Visible 3457 3458 3459Syntax: 3460 3461@example 3462pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3463@end example 3464 3465For the semantics of this pragma, see the entry for aspect @cite{Extensions_Visible} 3466in the SPARK 2014 Reference Manual, section 6.1.7. 3467 3468@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3469@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{5a} 3470@section Pragma External 3471 3472 3473Syntax: 3474 3475@example 3476pragma External ( 3477 [ Convention =>] convention_IDENTIFIER, 3478 [ Entity =>] LOCAL_NAME 3479 [, [External_Name =>] static_string_EXPRESSION ] 3480 [, [Link_Name =>] static_string_EXPRESSION ]); 3481@end example 3482 3483This pragma is identical in syntax and semantics to pragma 3484@cite{Export} as defined in the Ada Reference Manual. It is 3485provided for compatibility with some Ada 83 compilers that 3486used this pragma for exactly the same purposes as pragma 3487@cite{Export} before the latter was standardized. 3488 3489@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3490@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{5b} 3491@section Pragma External_Name_Casing 3492 3493 3494@geindex Dec Ada 83 casing compatibility 3495 3496@geindex External Names 3497@geindex casing 3498 3499@geindex Casing of External names 3500 3501Syntax: 3502 3503@example 3504pragma External_Name_Casing ( 3505 Uppercase | Lowercase 3506 [, Uppercase | Lowercase | As_Is]); 3507@end example 3508 3509This pragma provides control over the casing of external names associated 3510with Import and Export pragmas. There are two cases to consider: 3511 3512 3513@itemize * 3514 3515@item 3516Implicit external names 3517 3518Implicit external names are derived from identifiers. The most common case 3519arises when a standard Ada Import or Export pragma is used with only two 3520arguments, as in: 3521 3522@example 3523pragma Import (C, C_Routine); 3524@end example 3525 3526Since Ada is a case-insensitive language, the spelling of the identifier in 3527the Ada source program does not provide any information on the desired 3528casing of the external name, and so a convention is needed. In GNAT the 3529default treatment is that such names are converted to all lower case 3530letters. This corresponds to the normal C style in many environments. 3531The first argument of pragma @cite{External_Name_Casing} can be used to 3532control this treatment. If @cite{Uppercase} is specified, then the name 3533will be forced to all uppercase letters. If @cite{Lowercase} is specified, 3534then the normal default of all lower case letters will be used. 3535 3536This same implicit treatment is also used in the case of extended DEC Ada 83 3537compatible Import and Export pragmas where an external name is explicitly 3538specified using an identifier rather than a string. 3539 3540@item 3541Explicit external names 3542 3543Explicit external names are given as string literals. The most common case 3544arises when a standard Ada Import or Export pragma is used with three 3545arguments, as in: 3546 3547@example 3548pragma Import (C, C_Routine, "C_routine"); 3549@end example 3550 3551In this case, the string literal normally provides the exact casing required 3552for the external name. The second argument of pragma 3553@cite{External_Name_Casing} may be used to modify this behavior. 3554If @cite{Uppercase} is specified, then the name 3555will be forced to all uppercase letters. If @cite{Lowercase} is specified, 3556then the name will be forced to all lowercase letters. A specification of 3557@cite{As_Is} provides the normal default behavior in which the casing is 3558taken from the string provided. 3559@end itemize 3560 3561This pragma may appear anywhere that a pragma is valid. In particular, it 3562can be used as a configuration pragma in the @code{gnat.adc} file, in which 3563case it applies to all subsequent compilations, or it can be used as a program 3564unit pragma, in which case it only applies to the current unit, or it can 3565be used more locally to control individual Import/Export pragmas. 3566 3567It was primarily intended for use with OpenVMS systems, where many 3568compilers convert all symbols to upper case by default. For interfacing to 3569such compilers (e.g., the DEC C compiler), it may be convenient to use 3570the pragma: 3571 3572@example 3573pragma External_Name_Casing (Uppercase, Uppercase); 3574@end example 3575 3576to enforce the upper casing of all external symbols. 3577 3578@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 3579@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{5c} 3580@section Pragma Fast_Math 3581 3582 3583Syntax: 3584 3585@example 3586pragma Fast_Math; 3587@end example 3588 3589This is a configuration pragma which activates a mode in which speed is 3590considered more important for floating-point operations than absolutely 3591accurate adherence to the requirements of the standard. Currently the 3592following operations are affected: 3593 3594 3595@table @asis 3596 3597@item @emph{Complex Multiplication} 3598 3599The normal simple formula for complex multiplication can result in intermediate 3600overflows for numbers near the end of the range. The Ada standard requires that 3601this situation be detected and corrected by scaling, but in Fast_Math mode such 3602cases will simply result in overflow. Note that to take advantage of this you 3603must instantiate your own version of @cite{Ada.Numerics.Generic_Complex_Types} 3604under control of the pragma, rather than use the preinstantiated versions. 3605@end table 3606 3607@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 3608@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{5d} 3609@section Pragma Favor_Top_Level 3610 3611 3612Syntax: 3613 3614@example 3615pragma Favor_Top_Level (type_NAME); 3616@end example 3617 3618The named type must be an access-to-subprogram type. This pragma is an 3619efficiency hint to the compiler, regarding the use of 'Access or 3620'Unrestricted_Access on nested (non-library-level) subprograms. The 3621pragma means that nested subprograms are not used with this type, or 3622are rare, so that the generated code should be efficient in the 3623top-level case. When this pragma is used, dynamically generated 3624trampolines may be used on some targets for nested subprograms. 3625See also the No_Implicit_Dynamic_Code restriction. 3626 3627@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 3628@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{5e} 3629@section Pragma Finalize_Storage_Only 3630 3631 3632Syntax: 3633 3634@example 3635pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3636@end example 3637 3638This pragma allows the compiler not to emit a Finalize call for objects 3639defined at the library level. This is mostly useful for types where 3640finalization is only used to deal with storage reclamation since in most 3641environments it is not necessary to reclaim memory just before terminating 3642execution, hence the name. 3643 3644@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 3645@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{5f} 3646@section Pragma Float_Representation 3647 3648 3649Syntax: 3650 3651@example 3652pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3653 3654FLOAT_REP ::= VAX_Float | IEEE_Float 3655@end example 3656 3657In the one argument form, this pragma is a configuration pragma which 3658allows control over the internal representation chosen for the predefined 3659floating point types declared in the packages @cite{Standard} and 3660@cite{System}. This pragma is only provided for compatibility and has no effect. 3661 3662The two argument form specifies the representation to be used for 3663the specified floating-point type. The argument must 3664be @cite{IEEE_Float} to specify the use of IEEE format, as follows: 3665 3666 3667@itemize * 3668 3669@item 3670For a digits value of 6, 32-bit IEEE short format will be used. 3671 3672@item 3673For a digits value of 15, 64-bit IEEE long format will be used. 3674 3675@item 3676No other value of digits is permitted. 3677@end itemize 3678 3679@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 3680@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{60} 3681@section Pragma Ghost 3682 3683 3684Syntax: 3685 3686@example 3687pragma Ghost [ (boolean_EXPRESSION) ]; 3688@end example 3689 3690For the semantics of this pragma, see the entry for aspect @cite{Ghost} in the SPARK 36912014 Reference Manual, section 6.9. 3692 3693@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 3694@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{61} 3695@section Pragma Global 3696 3697 3698Syntax: 3699 3700@example 3701pragma Global (GLOBAL_SPECIFICATION); 3702 3703GLOBAL_SPECIFICATION ::= 3704 null 3705 | (GLOBAL_LIST) 3706 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 3707 3708MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 3709 3710MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 3711GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 3712GLOBAL_ITEM ::= NAME 3713@end example 3714 3715For the semantics of this pragma, see the entry for aspect @cite{Global} in the 3716SPARK 2014 Reference Manual, section 6.1.4. 3717 3718@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 3719@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{62} 3720@section Pragma Ident 3721 3722 3723Syntax: 3724 3725@example 3726pragma Ident (static_string_EXPRESSION); 3727@end example 3728 3729This pragma is identical in effect to pragma @cite{Comment}. It is provided 3730for compatibility with other Ada compilers providing this pragma. 3731 3732@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 3733@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{63} 3734@section Pragma Ignore_Pragma 3735 3736 3737Syntax: 3738 3739@example 3740pragma Ignore_Pragma (pragma_IDENTIFIER); 3741@end example 3742 3743This is a configuration pragma 3744that takes a single argument that is a simple identifier. Any subsequent 3745use of a pragma whose pragma identifier matches this argument will be 3746silently ignored. This may be useful when legacy code or code intended 3747for compilation with some other compiler contains pragmas that match the 3748name, but not the exact implementation, of a @cite{GNAT} pragma. The use of this 3749pragma allows such pragmas to be ignored, which may be useful in @cite{CodePeer} 3750mode, or during porting of legacy code. 3751 3752@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 3753@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{64} 3754@section Pragma Implementation_Defined 3755 3756 3757Syntax: 3758 3759@example 3760pragma Implementation_Defined (local_NAME); 3761@end example 3762 3763This pragma marks a previously declared entioty as implementation-defined. 3764For an overloaded entity, applies to the most recent homonym. 3765 3766@example 3767pragma Implementation_Defined; 3768@end example 3769 3770The form with no arguments appears anywhere within a scope, most 3771typically a package spec, and indicates that all entities that are 3772defined within the package spec are Implementation_Defined. 3773 3774This pragma is used within the GNAT runtime library to identify 3775implementation-defined entities introduced in language-defined units, 3776for the purpose of implementing the No_Implementation_Identifiers 3777restriction. 3778 3779@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 3780@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{65} 3781@section Pragma Implemented 3782 3783 3784Syntax: 3785 3786@example 3787pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 3788 3789implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 3790@end example 3791 3792This is an Ada 2012 representation pragma which applies to protected, task 3793and synchronized interface primitives. The use of pragma Implemented provides 3794a way to impose a static requirement on the overriding operation by adhering 3795to one of the three implementation kinds: entry, protected procedure or any of 3796the above. This pragma is available in all earlier versions of Ada as an 3797implementation-defined pragma. 3798 3799@example 3800type Synch_Iface is synchronized interface; 3801procedure Prim_Op (Obj : in out Iface) is abstract; 3802pragma Implemented (Prim_Op, By_Protected_Procedure); 3803 3804protected type Prot_1 is new Synch_Iface with 3805 procedure Prim_Op; -- Legal 3806end Prot_1; 3807 3808protected type Prot_2 is new Synch_Iface with 3809 entry Prim_Op; -- Illegal 3810end Prot_2; 3811 3812task type Task_Typ is new Synch_Iface with 3813 entry Prim_Op; -- Illegal 3814end Task_Typ; 3815@end example 3816 3817When applied to the procedure_or_entry_NAME of a requeue statement, pragma 3818Implemented determines the runtime behavior of the requeue. Implementation kind 3819By_Entry guarantees that the action of requeueing will proceed from an entry to 3820another entry. Implementation kind By_Protected_Procedure transforms the 3821requeue into a dispatching call, thus eliminating the chance of blocking. Kind 3822By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 3823the target's overriding subprogram kind. 3824 3825@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 3826@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{66} 3827@section Pragma Implicit_Packing 3828 3829 3830@geindex Rational Profile 3831 3832Syntax: 3833 3834@example 3835pragma Implicit_Packing; 3836@end example 3837 3838This is a configuration pragma that requests implicit packing for packed 3839arrays for which a size clause is given but no explicit pragma Pack or 3840specification of Component_Size is present. It also applies to records 3841where no record representation clause is present. Consider this example: 3842 3843@example 3844type R is array (0 .. 7) of Boolean; 3845for R'Size use 8; 3846@end example 3847 3848In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 3849does not change the layout of a composite object. So the Size clause in the 3850above example is normally rejected, since the default layout of the array uses 38518-bit components, and thus the array requires a minimum of 64 bits. 3852 3853If this declaration is compiled in a region of code covered by an occurrence 3854of the configuration pragma Implicit_Packing, then the Size clause in this 3855and similar examples will cause implicit packing and thus be accepted. For 3856this implicit packing to occur, the type in question must be an array of small 3857components whose size is known at compile time, and the Size clause must 3858specify the exact size that corresponds to the number of elements in the array 3859multiplied by the size in bits of the component type (both single and 3860multi-dimensioned arrays can be controlled with this pragma). 3861 3862@geindex Array packing 3863 3864Similarly, the following example shows the use in the record case 3865 3866@example 3867type r is record 3868 a, b, c, d, e, f, g, h : boolean; 3869 chr : character; 3870end record; 3871for r'size use 16; 3872@end example 3873 3874Without a pragma Pack, each Boolean field requires 8 bits, so the 3875minimum size is 72 bits, but with a pragma Pack, 16 bits would be 3876sufficient. The use of pragma Implicit_Packing allows this record 3877declaration to compile without an explicit pragma Pack. 3878 3879@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 3880@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{67} 3881@section Pragma Import_Function 3882 3883 3884Syntax: 3885 3886@example 3887pragma Import_Function ( 3888 [Internal =>] LOCAL_NAME, 3889 [, [External =>] EXTERNAL_SYMBOL] 3890 [, [Parameter_Types =>] PARAMETER_TYPES] 3891 [, [Result_Type =>] SUBTYPE_MARK] 3892 [, [Mechanism =>] MECHANISM] 3893 [, [Result_Mechanism =>] MECHANISM_NAME]); 3894 3895EXTERNAL_SYMBOL ::= 3896 IDENTIFIER 3897| static_string_EXPRESSION 3898 3899PARAMETER_TYPES ::= 3900 null 3901| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3902 3903TYPE_DESIGNATOR ::= 3904 subtype_NAME 3905| subtype_Name ' Access 3906 3907MECHANISM ::= 3908 MECHANISM_NAME 3909| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3910 3911MECHANISM_ASSOCIATION ::= 3912 [formal_parameter_NAME =>] MECHANISM_NAME 3913 3914MECHANISM_NAME ::= 3915 Value 3916| Reference 3917@end example 3918 3919This pragma is used in conjunction with a pragma @cite{Import} to 3920specify additional information for an imported function. The pragma 3921@cite{Import} (or equivalent pragma @cite{Interface}) must precede the 3922@cite{Import_Function} pragma and both must appear in the same 3923declarative part as the function specification. 3924 3925The @cite{Internal} argument must uniquely designate 3926the function to which the 3927pragma applies. If more than one function name exists of this name in 3928the declarative part you must use the @cite{Parameter_Types} and 3929@cite{Result_Type} parameters to achieve the required unique 3930designation. Subtype marks in these parameters must exactly match the 3931subtypes in the corresponding function specification, using positional 3932notation to match parameters with subtype marks. 3933The form with an @cite{'Access} attribute can be used to match an 3934anonymous access parameter. 3935 3936You may optionally use the @cite{Mechanism} and @cite{Result_Mechanism} 3937parameters to specify passing mechanisms for the 3938parameters and result. If you specify a single mechanism name, it 3939applies to all parameters. Otherwise you may specify a mechanism on a 3940parameter by parameter basis using either positional or named 3941notation. If the mechanism is not specified, the default mechanism 3942is used. 3943 3944@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 3945@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{68} 3946@section Pragma Import_Object 3947 3948 3949Syntax: 3950 3951@example 3952pragma Import_Object 3953 [Internal =>] LOCAL_NAME 3954 [, [External =>] EXTERNAL_SYMBOL] 3955 [, [Size =>] EXTERNAL_SYMBOL]); 3956 3957EXTERNAL_SYMBOL ::= 3958 IDENTIFIER 3959| static_string_EXPRESSION 3960@end example 3961 3962This pragma designates an object as imported, and apart from the 3963extended rules for external symbols, is identical in effect to the use of 3964the normal @cite{Import} pragma applied to an object. Unlike the 3965subprogram case, you need not use a separate @cite{Import} pragma, 3966although you may do so (and probably should do so from a portability 3967point of view). @cite{size} is syntax checked, but otherwise ignored by 3968GNAT. 3969 3970@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 3971@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{69} 3972@section Pragma Import_Procedure 3973 3974 3975Syntax: 3976 3977@example 3978pragma Import_Procedure ( 3979 [Internal =>] LOCAL_NAME 3980 [, [External =>] EXTERNAL_SYMBOL] 3981 [, [Parameter_Types =>] PARAMETER_TYPES] 3982 [, [Mechanism =>] MECHANISM]); 3983 3984EXTERNAL_SYMBOL ::= 3985 IDENTIFIER 3986| static_string_EXPRESSION 3987 3988PARAMETER_TYPES ::= 3989 null 3990| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3991 3992TYPE_DESIGNATOR ::= 3993 subtype_NAME 3994| subtype_Name ' Access 3995 3996MECHANISM ::= 3997 MECHANISM_NAME 3998| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3999 4000MECHANISM_ASSOCIATION ::= 4001 [formal_parameter_NAME =>] MECHANISM_NAME 4002 4003MECHANISM_NAME ::= Value | Reference 4004@end example 4005 4006This pragma is identical to @cite{Import_Function} except that it 4007applies to a procedure rather than a function and the parameters 4008@cite{Result_Type} and @cite{Result_Mechanism} are not permitted. 4009 4010@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4011@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{6a} 4012@section Pragma Import_Valued_Procedure 4013 4014 4015Syntax: 4016 4017@example 4018pragma Import_Valued_Procedure ( 4019 [Internal =>] LOCAL_NAME 4020 [, [External =>] EXTERNAL_SYMBOL] 4021 [, [Parameter_Types =>] PARAMETER_TYPES] 4022 [, [Mechanism =>] MECHANISM]); 4023 4024EXTERNAL_SYMBOL ::= 4025 IDENTIFIER 4026| static_string_EXPRESSION 4027 4028PARAMETER_TYPES ::= 4029 null 4030| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4031 4032TYPE_DESIGNATOR ::= 4033 subtype_NAME 4034| subtype_Name ' Access 4035 4036MECHANISM ::= 4037 MECHANISM_NAME 4038| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4039 4040MECHANISM_ASSOCIATION ::= 4041 [formal_parameter_NAME =>] MECHANISM_NAME 4042 4043MECHANISM_NAME ::= Value | Reference 4044@end example 4045 4046This pragma is identical to @cite{Import_Procedure} except that the 4047first parameter of @cite{LOCAL_NAME}, which must be present, must be of 4048mode @cite{OUT}, and externally the subprogram is treated as a function 4049with this parameter as the result of the function. The purpose of this 4050capability is to allow the use of @cite{OUT} and @cite{IN OUT} 4051parameters in interfacing to external functions (which are not permitted 4052in Ada functions). You may optionally use the @cite{Mechanism} 4053parameters to specify passing mechanisms for the parameters. 4054If you specify a single mechanism name, it applies to all parameters. 4055Otherwise you may specify a mechanism on a parameter by parameter 4056basis using either positional or named notation. If the mechanism is not 4057specified, the default mechanism is used. 4058 4059Note that it is important to use this pragma in conjunction with a separate 4060pragma Import that specifies the desired convention, since otherwise the 4061default convention is Ada, which is almost certainly not what is required. 4062 4063@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4064@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{6b} 4065@section Pragma Independent 4066 4067 4068Syntax: 4069 4070@example 4071pragma Independent (Local_NAME); 4072@end example 4073 4074This pragma is standard in Ada 2012 mode (which also provides an aspect 4075of the same name). It is also available as an implementation-defined 4076pragma in all earlier versions. It specifies that the 4077designated object or all objects of the designated type must be 4078independently addressable. This means that separate tasks can safely 4079manipulate such objects. For example, if two components of a record are 4080independent, then two separate tasks may access these two components. 4081This may place 4082constraints on the representation of the object (for instance prohibiting 4083tight packing). 4084 4085@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4086@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{6c} 4087@section Pragma Independent_Components 4088 4089 4090Syntax: 4091 4092@example 4093pragma Independent_Components (Local_NAME); 4094@end example 4095 4096This pragma is standard in Ada 2012 mode (which also provides an aspect 4097of the same name). It is also available as an implementation-defined 4098pragma in all earlier versions. It specifies that the components of the 4099designated object, or the components of each object of the designated 4100type, must be 4101independently addressable. This means that separate tasks can safely 4102manipulate separate components in the composite object. This may place 4103constraints on the representation of the object (for instance prohibiting 4104tight packing). 4105 4106@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4107@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{6d} 4108@section Pragma Initial_Condition 4109 4110 4111Syntax: 4112 4113@example 4114pragma Initial_Condition (boolean_EXPRESSION); 4115@end example 4116 4117For the semantics of this pragma, see the entry for aspect @cite{Initial_Condition} 4118in the SPARK 2014 Reference Manual, section 7.1.6. 4119 4120@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4121@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{6e} 4122@section Pragma Initialize_Scalars 4123 4124 4125@geindex debugging with Initialize_Scalars 4126 4127Syntax: 4128 4129@example 4130pragma Initialize_Scalars; 4131@end example 4132 4133This pragma is similar to @cite{Normalize_Scalars} conceptually but has 4134two important differences. First, there is no requirement for the pragma 4135to be used uniformly in all units of a partition, in particular, it is fine 4136to use this just for some or all of the application units of a partition, 4137without needing to recompile the run-time library. 4138 4139In the case where some units are compiled with the pragma, and some without, 4140then a declaration of a variable where the type is defined in package 4141Standard or is locally declared will always be subject to initialization, 4142as will any declaration of a scalar variable. For composite variables, 4143whether the variable is initialized may also depend on whether the package 4144in which the type of the variable is declared is compiled with the pragma. 4145 4146The other important difference is that you can control the value used 4147for initializing scalar objects. At bind time, you can select several 4148options for initialization. You can 4149initialize with invalid values (similar to Normalize_Scalars, though for 4150Initialize_Scalars it is not always possible to determine the invalid 4151values in complex cases like signed component fields with non-standard 4152sizes). You can also initialize with high or 4153low values, or with a specified bit pattern. See the GNAT 4154User's Guide for binder options for specifying these cases. 4155 4156This means that you can compile a program, and then without having to 4157recompile the program, you can run it with different values being used 4158for initializing otherwise uninitialized values, to test if your program 4159behavior depends on the choice. Of course the behavior should not change, 4160and if it does, then most likely you have an incorrect reference to an 4161uninitialized value. 4162 4163It is even possible to change the value at execution time eliminating even 4164the need to rebind with a different switch using an environment variable. 4165See the GNAT User's Guide for details. 4166 4167Note that pragma @cite{Initialize_Scalars} is particularly useful in 4168conjunction with the enhanced validity checking that is now provided 4169in GNAT, which checks for invalid values under more conditions. 4170Using this feature (see description of the @emph{-gnatV} flag in the 4171GNAT User's Guide) in conjunction with 4172pragma @cite{Initialize_Scalars} 4173provides a powerful new tool to assist in the detection of problems 4174caused by uninitialized variables. 4175 4176Note: the use of @cite{Initialize_Scalars} has a fairly extensive 4177effect on the generated code. This may cause your code to be 4178substantially larger. It may also cause an increase in the amount 4179of stack required, so it is probably a good idea to turn on stack 4180checking (see description of stack checking in the GNAT 4181User's Guide) when using this pragma. 4182 4183@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4184@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{6f} 4185@section Pragma Initializes 4186 4187 4188Syntax: 4189 4190@example 4191pragma Initializes (INITIALIZATION_LIST); 4192 4193INITIALIZATION_LIST ::= 4194 null 4195 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4196 4197INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4198 4199INPUT_LIST ::= 4200 null 4201 | INPUT 4202 | (INPUT @{, INPUT@}) 4203 4204INPUT ::= name 4205@end example 4206 4207For the semantics of this pragma, see the entry for aspect @cite{Initializes} in the 4208SPARK 2014 Reference Manual, section 7.1.5. 4209 4210@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4211@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{70} 4212@section Pragma Inline_Always 4213 4214 4215Syntax: 4216 4217@example 4218pragma Inline_Always (NAME [, NAME]); 4219@end example 4220 4221Similar to pragma @cite{Inline} except that inlining is not subject to 4222the use of option @emph{-gnatn} or @emph{-gnatN} and the inlining 4223happens regardless of whether these options are used. 4224 4225@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4226@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{71} 4227@section Pragma Inline_Generic 4228 4229 4230Syntax: 4231 4232@example 4233pragma Inline_Generic (GNAME @{, GNAME@}); 4234 4235GNAME ::= generic_unit_NAME | generic_instance_NAME 4236@end example 4237 4238This pragma is provided for compatibility with Dec Ada 83. It has 4239no effect in @cite{GNAT} (which always inlines generics), other 4240than to check that the given names are all names of generic units or 4241generic instances. 4242 4243@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4244@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{72} 4245@section Pragma Interface 4246 4247 4248Syntax: 4249 4250@example 4251pragma Interface ( 4252 [Convention =>] convention_identifier, 4253 [Entity =>] local_NAME 4254 [, [External_Name =>] static_string_expression] 4255 [, [Link_Name =>] static_string_expression]); 4256@end example 4257 4258This pragma is identical in syntax and semantics to 4259the standard Ada pragma @cite{Import}. It is provided for compatibility 4260with Ada 83. The definition is upwards compatible both with pragma 4261@cite{Interface} as defined in the Ada 83 Reference Manual, and also 4262with some extended implementations of this pragma in certain Ada 83 4263implementations. The only difference between pragma @cite{Interface} 4264and pragma @cite{Import} is that there is special circuitry to allow 4265both pragmas to appear for the same subprogram entity (normally it 4266is illegal to have multiple @cite{Import} pragmas. This is useful in 4267maintaining Ada 83/Ada 95 compatibility and is compatible with other 4268Ada 83 compilers. 4269 4270@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4271@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{73} 4272@section Pragma Interface_Name 4273 4274 4275Syntax: 4276 4277@example 4278pragma Interface_Name ( 4279 [Entity =>] LOCAL_NAME 4280 [, [External_Name =>] static_string_EXPRESSION] 4281 [, [Link_Name =>] static_string_EXPRESSION]); 4282@end example 4283 4284This pragma provides an alternative way of specifying the interface name 4285for an interfaced subprogram, and is provided for compatibility with Ada 428683 compilers that use the pragma for this purpose. You must provide at 4287least one of @cite{External_Name} or @cite{Link_Name}. 4288 4289@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4290@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{74} 4291@section Pragma Interrupt_Handler 4292 4293 4294Syntax: 4295 4296@example 4297pragma Interrupt_Handler (procedure_LOCAL_NAME); 4298@end example 4299 4300This program unit pragma is supported for parameterless protected procedures 4301as described in Annex C of the Ada Reference Manual. On the AAMP target 4302the pragma can also be specified for nonprotected parameterless procedures 4303that are declared at the library level (which includes procedures 4304declared at the top level of a library package). In the case of AAMP, 4305when this pragma is applied to a nonprotected procedure, the instruction 4306@cite{IERET} is generated for returns from the procedure, enabling 4307maskable interrupts, in place of the normal return instruction. 4308 4309@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4310@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{75} 4311@section Pragma Interrupt_State 4312 4313 4314Syntax: 4315 4316@example 4317pragma Interrupt_State 4318 ([Name =>] value, 4319 [State =>] SYSTEM | RUNTIME | USER); 4320@end example 4321 4322Normally certain interrupts are reserved to the implementation. Any attempt 4323to attach an interrupt causes Program_Error to be raised, as described in 4324RM C.3.2(22). A typical example is the @cite{SIGINT} interrupt used in 4325many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4326reserved to the implementation, so that @code{Ctrl-C} can be used to 4327interrupt execution. Additionally, signals such as @cite{SIGSEGV}, 4328@cite{SIGABRT}, @cite{SIGFPE} and @cite{SIGILL} are often mapped to specific 4329Ada exceptions, or used to implement run-time functions such as the 4330@cite{abort} statement and stack overflow checking. 4331 4332Pragma @cite{Interrupt_State} provides a general mechanism for overriding 4333such uses of interrupts. It subsumes the functionality of pragma 4334@cite{Unreserve_All_Interrupts}. Pragma @cite{Interrupt_State} is not 4335available on Windows or VMS. On all other platforms than VxWorks, 4336it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4337and may be used to mark interrupts required by the board support package 4338as reserved. 4339 4340Interrupts can be in one of three states: 4341 4342 4343@itemize * 4344 4345@item 4346System 4347 4348The interrupt is reserved (no Ada handler can be installed), and the 4349Ada run-time may not install a handler. As a result you are guaranteed 4350standard system default action if this interrupt is raised. 4351 4352@item 4353Runtime 4354 4355The interrupt is reserved (no Ada handler can be installed). The run time 4356is allowed to install a handler for internal control purposes, but is 4357not required to do so. 4358 4359@item 4360User 4361 4362The interrupt is unreserved. The user may install a handler to provide 4363some other action. 4364@end itemize 4365 4366These states are the allowed values of the @cite{State} parameter of the 4367pragma. The @cite{Name} parameter is a value of the type 4368@cite{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4369@cite{Ada.Interrupts.Names}. 4370 4371This is a configuration pragma, and the binder will check that there 4372are no inconsistencies between different units in a partition in how a 4373given interrupt is specified. It may appear anywhere a pragma is legal. 4374 4375The effect is to move the interrupt to the specified state. 4376 4377By declaring interrupts to be SYSTEM, you guarantee the standard system 4378action, such as a core dump. 4379 4380By declaring interrupts to be USER, you guarantee that you can install 4381a handler. 4382 4383Note that certain signals on many operating systems cannot be caught and 4384handled by applications. In such cases, the pragma is ignored. See the 4385operating system documentation, or the value of the array @cite{Reserved} 4386declared in the spec of package @cite{System.OS_Interface}. 4387 4388Overriding the default state of signals used by the Ada runtime may interfere 4389with an application's runtime behavior in the cases of the synchronous signals, 4390and in the case of the signal used to implement the @cite{abort} statement. 4391 4392@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4393@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{76} 4394@section Pragma Invariant 4395 4396 4397Syntax: 4398 4399@example 4400pragma Invariant 4401 ([Entity =>] private_type_LOCAL_NAME, 4402 [Check =>] EXPRESSION 4403 [,[Message =>] String_Expression]); 4404@end example 4405 4406This pragma provides exactly the same capabilities as the Type_Invariant aspect 4407defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4408Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4409requires the use of the aspect syntax, which is not available except in 2012 4410mode, it is not possible to use the Type_Invariant aspect in earlier versions 4411of Ada. However the Invariant pragma may be used in any version of Ada. Also 4412note that the aspect Invariant is a synonym in GNAT for the aspect 4413Type_Invariant, but there is no pragma Type_Invariant. 4414 4415The pragma must appear within the visible part of the package specification, 4416after the type to which its Entity argument appears. As with the Invariant 4417aspect, the Check expression is not analyzed until the end of the visible 4418part of the package, so it may contain forward references. The Message 4419argument, if present, provides the exception message used if the invariant 4420is violated. If no Message parameter is provided, a default message that 4421identifies the line on which the pragma appears is used. 4422 4423It is permissible to have multiple Invariants for the same type entity, in 4424which case they are and'ed together. It is permissible to use this pragma 4425in Ada 2012 mode, but you cannot have both an invariant aspect and an 4426invariant pragma for the same entity. 4427 4428For further details on the use of this pragma, see the Ada 2012 documentation 4429of the Type_Invariant aspect. 4430 4431@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4432@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{77} 4433@section Pragma Keep_Names 4434 4435 4436Syntax: 4437 4438@example 4439pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4440@end example 4441 4442The @cite{LOCAL_NAME} argument 4443must refer to an enumeration first subtype 4444in the current declarative part. The effect is to retain the enumeration 4445literal names for use by @cite{Image} and @cite{Value} even if a global 4446@cite{Discard_Names} pragma applies. This is useful when you want to 4447generally suppress enumeration literal names and for example you therefore 4448use a @cite{Discard_Names} pragma in the @code{gnat.adc} file, but you 4449want to retain the names for specific enumeration types. 4450 4451@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4452@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{78} 4453@section Pragma License 4454 4455 4456@geindex License checking 4457 4458Syntax: 4459 4460@example 4461pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4462@end example 4463 4464This pragma is provided to allow automated checking for appropriate license 4465conditions with respect to the standard and modified GPL. A pragma 4466@cite{License}, which is a configuration pragma that typically appears at 4467the start of a source file or in a separate @code{gnat.adc} file, specifies 4468the licensing conditions of a unit as follows: 4469 4470 4471@itemize * 4472 4473@item 4474Unrestricted 4475This is used for a unit that can be freely used with no license restrictions. 4476Examples of such units are public domain units, and units from the Ada 4477Reference Manual. 4478 4479@item 4480GPL 4481This is used for a unit that is licensed under the unmodified GPL, and which 4482therefore cannot be @cite{with}'ed by a restricted unit. 4483 4484@item 4485Modified_GPL 4486This is used for a unit licensed under the GNAT modified GPL that includes 4487a special exception paragraph that specifically permits the inclusion of 4488the unit in programs without requiring the entire program to be released 4489under the GPL. 4490 4491@item 4492Restricted 4493This is used for a unit that is restricted in that it is not permitted to 4494depend on units that are licensed under the GPL. Typical examples are 4495proprietary code that is to be released under more restrictive license 4496conditions. Note that restricted units are permitted to @cite{with} units 4497which are licensed under the modified GPL (this is the whole point of the 4498modified GPL). 4499@end itemize 4500 4501Normally a unit with no @cite{License} pragma is considered to have an 4502unknown license, and no checking is done. However, standard GNAT headers 4503are recognized, and license information is derived from them as follows. 4504 4505A GNAT license header starts with a line containing 78 hyphens. The following 4506comment text is searched for the appearance of any of the following strings. 4507 4508If the string 'GNU General Public License' is found, then the unit is assumed 4509to have GPL license, unless the string 'As a special exception' follows, in 4510which case the license is assumed to be modified GPL. 4511 4512If one of the strings 4513'This specification is adapted from the Ada Semantic Interface' or 4514'This specification is derived from the Ada Reference Manual' is found 4515then the unit is assumed to be unrestricted. 4516 4517These default actions means that a program with a restricted license pragma 4518will automatically get warnings if a GPL unit is inappropriately 4519@cite{with}'ed. For example, the program: 4520 4521@example 4522with Sem_Ch3; 4523with GNAT.Sockets; 4524procedure Secret_Stuff is 4525 ... 4526end Secret_Stuff 4527@end example 4528 4529if compiled with pragma @cite{License} (@cite{Restricted}) in a 4530@code{gnat.adc} file will generate the warning: 4531 4532@example 45331. with Sem_Ch3; 4534 | 4535 >>> license of withed unit "Sem_Ch3" is incompatible 4536 45372. with GNAT.Sockets; 45383. procedure Secret_Stuff is 4539@end example 4540 4541Here we get a warning on @cite{Sem_Ch3} since it is part of the GNAT 4542compiler and is licensed under the 4543GPL, but no warning for @cite{GNAT.Sockets} which is part of the GNAT 4544run time, and is therefore licensed under the modified GPL. 4545 4546@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 4547@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{79} 4548@section Pragma Link_With 4549 4550 4551Syntax: 4552 4553@example 4554pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4555@end example 4556 4557This pragma is provided for compatibility with certain Ada 83 compilers. 4558It has exactly the same effect as pragma @cite{Linker_Options} except 4559that spaces occurring within one of the string expressions are treated 4560as separators. For example, in the following case: 4561 4562@example 4563pragma Link_With ("-labc -ldef"); 4564@end example 4565 4566results in passing the strings @cite{-labc} and @cite{-ldef} as two 4567separate arguments to the linker. In addition pragma Link_With allows 4568multiple arguments, with the same effect as successive pragmas. 4569 4570@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 4571@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{7a} 4572@section Pragma Linker_Alias 4573 4574 4575Syntax: 4576 4577@example 4578pragma Linker_Alias ( 4579 [Entity =>] LOCAL_NAME, 4580 [Target =>] static_string_EXPRESSION); 4581@end example 4582 4583@cite{LOCAL_NAME} must refer to an object that is declared at the library 4584level. This pragma establishes the given entity as a linker alias for the 4585given target. It is equivalent to @cite{__attribute__((alias))} in GNU C 4586and causes @cite{LOCAL_NAME} to be emitted as an alias for the symbol 4587@cite{static_string_EXPRESSION} in the object file, that is to say no space 4588is reserved for @cite{LOCAL_NAME} by the assembler and it will be resolved 4589to the same address as @cite{static_string_EXPRESSION} by the linker. 4590 4591The actual linker name for the target must be used (e.g., the fully 4592encoded name with qualification in Ada, or the mangled name in C++), 4593or it must be declared using the C convention with @cite{pragma Import} 4594or @cite{pragma Export}. 4595 4596Not all target machines support this pragma. On some of them it is accepted 4597only if @cite{pragma Weak_External} has been applied to @cite{LOCAL_NAME}. 4598 4599@example 4600-- Example of the use of pragma Linker_Alias 4601 4602package p is 4603 i : Integer := 1; 4604 pragma Export (C, i); 4605 4606 new_name_for_i : Integer; 4607 pragma Linker_Alias (new_name_for_i, "i"); 4608end p; 4609@end example 4610 4611@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 4612@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{7b} 4613@section Pragma Linker_Constructor 4614 4615 4616Syntax: 4617 4618@example 4619pragma Linker_Constructor (procedure_LOCAL_NAME); 4620@end example 4621 4622@cite{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4623is declared at the library level. A procedure to which this pragma is 4624applied will be treated as an initialization routine by the linker. 4625It is equivalent to @cite{__attribute__((constructor))} in GNU C and 4626causes @cite{procedure_LOCAL_NAME} to be invoked before the entry point 4627of the executable is called (or immediately after the shared library is 4628loaded if the procedure is linked in a shared library), in particular 4629before the Ada run-time environment is set up. 4630 4631Because of these specific contexts, the set of operations such a procedure 4632can perform is very limited and the type of objects it can manipulate is 4633essentially restricted to the elementary types. In particular, it must only 4634contain code to which pragma Restrictions (No_Elaboration_Code) applies. 4635 4636This pragma is used by GNAT to implement auto-initialization of shared Stand 4637Alone Libraries, which provides a related capability without the restrictions 4638listed above. Where possible, the use of Stand Alone Libraries is preferable 4639to the use of this pragma. 4640 4641@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 4642@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{7c} 4643@section Pragma Linker_Destructor 4644 4645 4646Syntax: 4647 4648@example 4649pragma Linker_Destructor (procedure_LOCAL_NAME); 4650@end example 4651 4652@cite{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4653is declared at the library level. A procedure to which this pragma is 4654applied will be treated as a finalization routine by the linker. 4655It is equivalent to @cite{__attribute__((destructor))} in GNU C and 4656causes @cite{procedure_LOCAL_NAME} to be invoked after the entry point 4657of the executable has exited (or immediately before the shared library 4658is unloaded if the procedure is linked in a shared library), in particular 4659after the Ada run-time environment is shut down. 4660 4661See @cite{pragma Linker_Constructor} for the set of restrictions that apply 4662because of these specific contexts. 4663 4664@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 4665@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{7d} 4666@section Pragma Linker_Section 4667 4668 4669Syntax: 4670 4671@example 4672pragma Linker_Section ( 4673 [Entity =>] LOCAL_NAME, 4674 [Section =>] static_string_EXPRESSION); 4675@end example 4676 4677@cite{LOCAL_NAME} must refer to an object, type, or subprogram that is 4678declared at the library level. This pragma specifies the name of the 4679linker section for the given entity. It is equivalent to 4680@cite{__attribute__((section))} in GNU C and causes @cite{LOCAL_NAME} to 4681be placed in the @cite{static_string_EXPRESSION} section of the 4682executable (assuming the linker doesn't rename the section). 4683GNAT also provides an implementation defined aspect of the same name. 4684 4685In the case of specifying this aspect for a type, the effect is to 4686specify the corresponding for all library level objects of the type which 4687do not have an explicit linker section set. Note that this only applies to 4688whole objects, not to components of composite objects. 4689 4690In the case of a subprogram, the linker section applies to all previously 4691declared matching overloaded subprograms in the current declarative part 4692which do not already have a linker section assigned. The linker section 4693aspect is useful in this case for specifying different linker sections 4694for different elements of such an overloaded set. 4695 4696Note that an empty string specifies that no linker section is specified. 4697This is not quite the same as omitting the pragma or aspect, since it 4698can be used to specify that one element of an overloaded set of subprograms 4699has the default linker section, or that one object of a type for which a 4700linker section is specified should has the default linker section. 4701 4702The compiler normally places library-level entities in standard sections 4703depending on the class: procedures and functions generally go in the 4704@cite{.text} section, initialized variables in the @cite{.data} section 4705and uninitialized variables in the @cite{.bss} section. 4706 4707Other, special sections may exist on given target machines to map special 4708hardware, for example I/O ports or flash memory. This pragma is a means to 4709defer the final layout of the executable to the linker, thus fully working 4710at the symbolic level with the compiler. 4711 4712Some file formats do not support arbitrary sections so not all target 4713machines support this pragma. The use of this pragma may cause a program 4714execution to be erroneous if it is used to place an entity into an 4715inappropriate section (e.g., a modified variable into the @cite{.text} 4716section). See also @cite{pragma Persistent_BSS}. 4717 4718@example 4719-- Example of the use of pragma Linker_Section 4720 4721package IO_Card is 4722 Port_A : Integer; 4723 pragma Volatile (Port_A); 4724 pragma Linker_Section (Port_A, ".bss.port_a"); 4725 4726 Port_B : Integer; 4727 pragma Volatile (Port_B); 4728 pragma Linker_Section (Port_B, ".bss.port_b"); 4729 4730 type Port_Type is new Integer with Linker_Section => ".bss"; 4731 PA : Port_Type with Linker_Section => ".bss.PA"; 4732 PB : Port_Type; -- ends up in linker section ".bss" 4733 4734 procedure Q with Linker_Section => "Qsection"; 4735end IO_Card; 4736@end example 4737 4738@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 4739@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{7e} 4740@section Pragma Lock_Free 4741 4742 4743Syntax: 4744This pragma may be specified for protected types or objects. It specifies that 4745the implementation of protected operations must be implemented without locks. 4746Compilation fails if the compiler cannot generate lock-free code for the 4747operations. 4748 4749@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 4750@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{7f} 4751@section Pragma Loop_Invariant 4752 4753 4754Syntax: 4755 4756@example 4757pragma Loop_Invariant ( boolean_EXPRESSION ); 4758@end example 4759 4760The effect of this pragma is similar to that of pragma @cite{Assert}, 4761except that in an @cite{Assertion_Policy} pragma, the identifier 4762@cite{Loop_Invariant} is used to control whether it is ignored or checked 4763(or disabled). 4764 4765@cite{Loop_Invariant} can only appear as one of the items in the sequence 4766of statements of a loop body, or nested inside block statements that 4767appear in the sequence of statements of a loop body. 4768The intention is that it be used to 4769represent a "loop invariant" assertion, i.e. something that is true each 4770time through the loop, and which can be used to show that the loop is 4771achieving its purpose. 4772 4773Multiple @cite{Loop_Invariant} and @cite{Loop_Variant} pragmas that 4774apply to the same loop should be grouped in the same sequence of 4775statements. 4776 4777To aid in writing such invariants, the special attribute @cite{Loop_Entry} 4778may be used to refer to the value of an expression on entry to the loop. This 4779attribute can only be used within the expression of a @cite{Loop_Invariant} 4780pragma. For full details, see documentation of attribute @cite{Loop_Entry}. 4781 4782@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 4783@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{80} 4784@section Pragma Loop_Optimize 4785 4786 4787Syntax: 4788 4789@example 4790pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 4791 4792OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 4793@end example 4794 4795This pragma must appear immediately within a loop statement. It allows the 4796programmer to specify optimization hints for the enclosing loop. The hints 4797are not mutually exclusive and can be freely mixed, but not all combinations 4798will yield a sensible outcome. 4799 4800There are five supported optimization hints for a loop: 4801 4802 4803@itemize * 4804 4805@item 4806Ivdep 4807 4808The programmer asserts that there are no loop-carried dependencies 4809which would prevent consecutive iterations of the loop from being 4810executed simultaneously. 4811 4812@item 4813No_Unroll 4814 4815The loop must not be unrolled. This is a strong hint: the compiler will not 4816unroll a loop marked with this hint. 4817 4818@item 4819Unroll 4820 4821The loop should be unrolled. This is a weak hint: the compiler will try to 4822apply unrolling to this loop preferably to other optimizations, notably 4823vectorization, but there is no guarantee that the loop will be unrolled. 4824 4825@item 4826No_Vector 4827 4828The loop must not be vectorized. This is a strong hint: the compiler will not 4829vectorize a loop marked with this hint. 4830 4831@item 4832Vector 4833 4834The loop should be vectorized. This is a weak hint: the compiler will try to 4835apply vectorization to this loop preferably to other optimizations, notably 4836unrolling, but there is no guarantee that the loop will be vectorized. 4837@end itemize 4838 4839These hints do not remove the need to pass the appropriate switches to the 4840compiler in order to enable the relevant optimizations, that is to say 4841@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 4842vectorization. 4843 4844@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 4845@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{81} 4846@section Pragma Loop_Variant 4847 4848 4849Syntax: 4850 4851@example 4852pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 4853LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 4854CHANGE_DIRECTION ::= Increases | Decreases 4855@end example 4856 4857@cite{Loop_Variant} can only appear as one of the items in the sequence 4858of statements of a loop body, or nested inside block statements that 4859appear in the sequence of statements of a loop body. 4860It allows the specification of quantities which must always 4861decrease or increase in successive iterations of the loop. In its simplest 4862form, just one expression is specified, whose value must increase or decrease 4863on each iteration of the loop. 4864 4865In a more complex form, multiple arguments can be given which are intepreted 4866in a nesting lexicographic manner. For example: 4867 4868@example 4869pragma Loop_Variant (Increases => X, Decreases => Y); 4870@end example 4871 4872specifies that each time through the loop either X increases, or X stays 4873the same and Y decreases. A @cite{Loop_Variant} pragma ensures that the 4874loop is making progress. It can be useful in helping to show informally 4875or prove formally that the loop always terminates. 4876 4877@cite{Loop_Variant} is an assertion whose effect can be controlled using 4878an @cite{Assertion_Policy} with a check name of @cite{Loop_Variant}. The 4879policy can be @cite{Check} to enable the loop variant check, @cite{Ignore} 4880to ignore the check (in which case the pragma has no effect on the program), 4881or @cite{Disable} in which case the pragma is not even checked for correct 4882syntax. 4883 4884Multiple @cite{Loop_Invariant} and @cite{Loop_Variant} pragmas that 4885apply to the same loop should be grouped in the same sequence of 4886statements. 4887 4888The @cite{Loop_Entry} attribute may be used within the expressions of the 4889@cite{Loop_Variant} pragma to refer to values on entry to the loop. 4890 4891@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 4892@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{82} 4893@section Pragma Machine_Attribute 4894 4895 4896Syntax: 4897 4898@example 4899pragma Machine_Attribute ( 4900 [Entity =>] LOCAL_NAME, 4901 [Attribute_Name =>] static_string_EXPRESSION 4902 [, [Info =>] static_EXPRESSION] ); 4903@end example 4904 4905Machine-dependent attributes can be specified for types and/or 4906declarations. This pragma is semantically equivalent to 4907@cite{__attribute__((`attribute_name}))` (if @cite{info} is not 4908specified) or @cite{__attribute__((`attribute_name`(`info}))) 4909in GNU C, where @code{attribute_name} is recognized by the 4910compiler middle-end or the @cite{TARGET_ATTRIBUTE_TABLE} machine 4911specific macro. A string literal for the optional parameter @cite{info} 4912is transformed into an identifier, which may make this pragma unusable 4913for some attributes. 4914For further information see @cite{GNU Compiler Collection (GCC) Internals}. 4915 4916@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 4917@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{83} 4918@section Pragma Main 4919 4920 4921Syntax: 4922 4923@example 4924pragma Main 4925 (MAIN_OPTION [, MAIN_OPTION]); 4926 4927MAIN_OPTION ::= 4928 [Stack_Size =>] static_integer_EXPRESSION 4929| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 4930| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 4931@end example 4932 4933This pragma is provided for compatibility with OpenVMS VAX Systems. It has 4934no effect in GNAT, other than being syntax checked. 4935 4936@node Pragma Main_Storage,Pragma No_Body,Pragma Main,Implementation Defined Pragmas 4937@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{84} 4938@section Pragma Main_Storage 4939 4940 4941Syntax: 4942 4943@example 4944pragma Main_Storage 4945 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 4946 4947MAIN_STORAGE_OPTION ::= 4948 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 4949| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 4950@end example 4951 4952This pragma is provided for compatibility with OpenVMS VAX Systems. It has 4953no effect in GNAT, other than being syntax checked. 4954 4955@node Pragma No_Body,Pragma No_Elaboration_Code_All,Pragma Main_Storage,Implementation Defined Pragmas 4956@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{85} 4957@section Pragma No_Body 4958 4959 4960Syntax: 4961 4962@example 4963pragma No_Body; 4964@end example 4965 4966There are a number of cases in which a package spec does not require a body, 4967and in fact a body is not permitted. GNAT will not permit the spec to be 4968compiled if there is a body around. The pragma No_Body allows you to provide 4969a body file, even in a case where no body is allowed. The body file must 4970contain only comments and a single No_Body pragma. This is recognized by 4971the compiler as indicating that no body is logically present. 4972 4973This is particularly useful during maintenance when a package is modified in 4974such a way that a body needed before is no longer needed. The provision of a 4975dummy body with a No_Body pragma ensures that there is no interference from 4976earlier versions of the package body. 4977 4978@node Pragma No_Elaboration_Code_All,Pragma No_Inline,Pragma No_Body,Implementation Defined Pragmas 4979@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{86} 4980@section Pragma No_Elaboration_Code_All 4981 4982 4983Syntax: 4984 4985@example 4986pragma No_Elaboration_Code_All [(program_unit_NAME)]; 4987@end example 4988 4989This is a program unit pragma (there is also an equivalent aspect of the 4990same name) that establishes the restriction @cite{No_Elaboration_Code} for 4991the current unit and any extended main source units (body and subunits. 4992It also has has the effect of enforcing a transitive application of this 4993aspect, so that if any unit is implicitly or explicitly WITH'ed by the 4994current unit, it must also have the No_Elaboration_Code_All aspect set. 4995It may be applied to package or subprogram specs or their generic versions. 4996 4997@node Pragma No_Inline,Pragma No_Return,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 4998@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{87} 4999@section Pragma No_Inline 5000 5001 5002Syntax: 5003 5004@example 5005pragma No_Inline (NAME @{, NAME@}); 5006@end example 5007 5008This pragma suppresses inlining for the callable entity or the instances of 5009the generic subprogram designated by @cite{NAME}, including inlining that 5010results from the use of pragma @cite{Inline}. This pragma is always active, 5011in particular it is not subject to the use of option @emph{-gnatn} or 5012@emph{-gnatN}. It is illegal to specify both pragma @cite{No_Inline} and 5013pragma @cite{Inline_Always} for the same @cite{NAME}. 5014 5015@node Pragma No_Return,Pragma No_Run_Time,Pragma No_Inline,Implementation Defined Pragmas 5016@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{88} 5017@section Pragma No_Return 5018 5019 5020Syntax: 5021 5022@example 5023pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5024@end example 5025 5026Each @cite{procedure_LOCAL_NAME} argument must refer to one or more procedure 5027declarations in the current declarative part. A procedure to which this 5028pragma is applied may not contain any explicit @cite{return} statements. 5029In addition, if the procedure contains any implicit returns from falling 5030off the end of a statement sequence, then execution of that implicit 5031return will cause Program_Error to be raised. 5032 5033One use of this pragma is to identify procedures whose only purpose is to raise 5034an exception. Another use of this pragma is to suppress incorrect warnings 5035about missing returns in functions, where the last statement of a function 5036statement sequence is a call to such a procedure. 5037 5038Note that in Ada 2005 mode, this pragma is part of the language. It is 5039available in all earlier versions of Ada as an implementation-defined 5040pragma. 5041 5042@node Pragma No_Run_Time,Pragma No_Strict_Aliasing,Pragma No_Return,Implementation Defined Pragmas 5043@anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{89} 5044@section Pragma No_Run_Time 5045 5046 5047Syntax: 5048 5049@example 5050pragma No_Run_Time; 5051@end example 5052 5053This is an obsolete configuration pragma that historically was used to 5054set up a runtime library with no object code. It is now used only for 5055internal testing. The pragma has been superseded by the reconfigurable 5056runtime capability of @cite{GNAT}. 5057 5058@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Run_Time,Implementation Defined Pragmas 5059@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{8a} 5060@section Pragma No_Strict_Aliasing 5061 5062 5063Syntax: 5064 5065@example 5066pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5067@end example 5068 5069@cite{type_LOCAL_NAME} must refer to an access type 5070declaration in the current declarative part. The effect is to inhibit 5071strict aliasing optimization for the given type. The form with no 5072arguments is a configuration pragma which applies to all access types 5073declared in units to which the pragma applies. For a detailed 5074description of the strict aliasing optimization, and the situations 5075in which it must be suppressed, see the section on Optimization and Strict Aliasing 5076in the @cite{GNAT User's Guide}. 5077 5078This pragma currently has no effects on access to unconstrained array types. 5079 5080@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5081@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{8b} 5082@section Pragma No_Tagged_Streams 5083 5084 5085Syntax: 5086 5087@example 5088pragma No_Tagged_Streams; 5089pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5090@end example 5091 5092Normally when a tagged type is introduced using a full type declaration, 5093part of the processing includes generating stream access routines to be 5094used by stream attributes referencing the type (or one of its subtypes 5095or derived types). This can involve the generation of significant amounts 5096of code which is wasted space if stream routines are not needed for the 5097type in question. 5098 5099The @cite{No_Tagged_Streams} pragma causes the generation of these stream 5100routines to be skipped, and any attempt to use stream operations on 5101types subject to this pragma will be statically rejected as illegal. 5102 5103There are two forms of the pragma. The form with no arguments must appear 5104in a declarative sequence or in the declarations of a package spec. This 5105pragma affects all subsequent root tagged types declared in the declaration 5106sequence, and specifies that no stream routines be generated. The form with 5107an argument (for which there is also a corresponding aspect) specifies a 5108single root tagged type for which stream routines are not to be generated. 5109 5110Once the pragma has been given for a particular root tagged type, all subtypes 5111and derived types of this type inherit the pragma automatically, so the effect 5112applies to a complete hierarchy (this is necessary to deal with the class-wide 5113dispatching versions of the stream routines). 5114 5115@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5116@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{8c} 5117@section Pragma Normalize_Scalars 5118 5119 5120Syntax: 5121 5122@example 5123pragma Normalize_Scalars; 5124@end example 5125 5126This is a language defined pragma which is fully implemented in GNAT. The 5127effect is to cause all scalar objects that are not otherwise initialized 5128to be initialized. The initial values are implementation dependent and 5129are as follows: 5130 5131 5132@table @asis 5133 5134@item @emph{Standard.Character} 5135 5136Objects whose root type is Standard.Character are initialized to 5137Character'Last unless the subtype range excludes NUL (in which case 5138NUL is used). This choice will always generate an invalid value if 5139one exists. 5140 5141@item @emph{Standard.Wide_Character} 5142 5143Objects whose root type is Standard.Wide_Character are initialized to 5144Wide_Character'Last unless the subtype range excludes NUL (in which case 5145NUL is used). This choice will always generate an invalid value if 5146one exists. 5147 5148@item @emph{Standard.Wide_Wide_Character} 5149 5150Objects whose root type is Standard.Wide_Wide_Character are initialized to 5151the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5152which case NUL is used). This choice will always generate an invalid value if 5153one exists. 5154 5155@item @emph{Integer types} 5156 5157Objects of an integer type are treated differently depending on whether 5158negative values are present in the subtype. If no negative values are 5159present, then all one bits is used as the initial value except in the 5160special case where zero is excluded from the subtype, in which case 5161all zero bits are used. This choice will always generate an invalid 5162value if one exists. 5163 5164For subtypes with negative values present, the largest negative number 5165is used, except in the unusual case where this largest negative number 5166is in the subtype, and the largest positive number is not, in which case 5167the largest positive value is used. This choice will always generate 5168an invalid value if one exists. 5169 5170@item @emph{Floating-Point Types} 5171 5172Objects of all floating-point types are initialized to all 1-bits. For 5173standard IEEE format, this corresponds to a NaN (not a number) which is 5174indeed an invalid value. 5175 5176@item @emph{Fixed-Point Types} 5177 5178Objects of all fixed-point types are treated as described above for integers, 5179with the rules applying to the underlying integer value used to represent 5180the fixed-point value. 5181 5182@item @emph{Modular types} 5183 5184Objects of a modular type are initialized to all one bits, except in 5185the special case where zero is excluded from the subtype, in which 5186case all zero bits are used. This choice will always generate an 5187invalid value if one exists. 5188 5189@item @emph{Enumeration types} 5190 5191Objects of an enumeration type are initialized to all one-bits, i.e., to 5192the value @cite{2 ** typ'Size - 1} unless the subtype excludes the literal 5193whose Pos value is zero, in which case a code of zero is used. This choice 5194will always generate an invalid value if one exists. 5195@end table 5196 5197@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5198@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{8d}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{8e} 5199@section Pragma Obsolescent 5200 5201 5202Syntax: 5203 5204@example 5205pragma Obsolescent; 5206 5207pragma Obsolescent ( 5208 [Message =>] static_string_EXPRESSION 5209[,[Version =>] Ada_05]]); 5210 5211pragma Obsolescent ( 5212 [Entity =>] NAME 5213[,[Message =>] static_string_EXPRESSION 5214[,[Version =>] Ada_05]] ); 5215@end example 5216 5217This pragma can occur immediately following a declaration of an entity, 5218including the case of a record component. If no Entity argument is present, 5219then this declaration is the one to which the pragma applies. If an Entity 5220parameter is present, it must either match the name of the entity in this 5221declaration, or alternatively, the pragma can immediately follow an enumeration 5222type declaration, where the Entity argument names one of the enumeration 5223literals. 5224 5225This pragma is used to indicate that the named entity 5226is considered obsolescent and should not be used. Typically this is 5227used when an API must be modified by eventually removing or modifying 5228existing subprograms or other entities. The pragma can be used at an 5229intermediate stage when the entity is still present, but will be 5230removed later. 5231 5232The effect of this pragma is to output a warning message on a reference to 5233an entity thus marked that the subprogram is obsolescent if the appropriate 5234warning option in the compiler is activated. If the Message parameter is 5235present, then a second warning message is given containing this text. In 5236addition, a reference to the entity is considered to be a violation of pragma 5237Restrictions (No_Obsolescent_Features). 5238 5239This pragma can also be used as a program unit pragma for a package, 5240in which case the entity name is the name of the package, and the 5241pragma indicates that the entire package is considered 5242obsolescent. In this case a client @cite{with}'ing such a package 5243violates the restriction, and the @cite{with} statement is 5244flagged with warnings if the warning option is set. 5245 5246If the Version parameter is present (which must be exactly 5247the identifier Ada_05, no other argument is allowed), then the 5248indication of obsolescence applies only when compiling in Ada 2005 5249mode. This is primarily intended for dealing with the situations 5250in the predefined library where subprograms or packages 5251have become defined as obsolescent in Ada 2005 5252(e.g., in Ada.Characters.Handling), but may be used anywhere. 5253 5254The following examples show typical uses of this pragma: 5255 5256@example 5257package p is 5258 pragma Obsolescent (p, Message => "use pp instead of p"); 5259end p; 5260 5261package q is 5262 procedure q2; 5263 pragma Obsolescent ("use q2new instead"); 5264 5265 type R is new integer; 5266 pragma Obsolescent 5267 (Entity => R, 5268 Message => "use RR in Ada 2005", 5269 Version => Ada_05); 5270 5271 type M is record 5272 F1 : Integer; 5273 F2 : Integer; 5274 pragma Obsolescent; 5275 F3 : Integer; 5276 end record; 5277 5278 type E is (a, bc, 'd', quack); 5279 pragma Obsolescent (Entity => bc) 5280 pragma Obsolescent (Entity => 'd') 5281 5282 function "+" 5283 (a, b : character) return character; 5284 pragma Obsolescent (Entity => "+"); 5285end; 5286@end example 5287 5288Note that, as for all pragmas, if you use a pragma argument identifier, 5289then all subsequent parameters must also use a pragma argument identifier. 5290So if you specify "Entity =>" for the Entity argument, and a Message 5291argument is present, it must be preceded by "Message =>". 5292 5293@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5294@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{8f} 5295@section Pragma Optimize_Alignment 5296 5297 5298@geindex Alignment 5299@geindex default settings 5300 5301Syntax: 5302 5303@example 5304pragma Optimize_Alignment (TIME | SPACE | OFF); 5305@end example 5306 5307This is a configuration pragma which affects the choice of default alignments 5308for types and objects where no alignment is explicitly specified. There is a 5309time/space trade-off in the selection of these values. Large alignments result 5310in more efficient code, at the expense of larger data space, since sizes have 5311to be increased to match these alignments. Smaller alignments save space, but 5312the access code is slower. The normal choice of default alignments for types 5313and individual alignment promotions for objects (which is what you get if you 5314do not use this pragma, or if you use an argument of OFF), tries to balance 5315these two requirements. 5316 5317Specifying SPACE causes smaller default alignments to be chosen in two cases. 5318First any packed record is given an alignment of 1. Second, if a size is given 5319for the type, then the alignment is chosen to avoid increasing this size. For 5320example, consider: 5321 5322@example 5323type R is record 5324 X : Integer; 5325 Y : Character; 5326end record; 5327 5328for R'Size use 5*8; 5329@end example 5330 5331In the default mode, this type gets an alignment of 4, so that access to the 5332Integer field X are efficient. But this means that objects of the type end up 5333with a size of 8 bytes. This is a valid choice, since sizes of objects are 5334allowed to be bigger than the size of the type, but it can waste space if for 5335example fields of type R appear in an enclosing record. If the above type is 5336compiled in @cite{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5337 5338However, there is one case in which SPACE is ignored. If a variable length 5339record (that is a discriminated record with a component which is an array 5340whose length depends on a discriminant), has a pragma Pack, then it is not 5341in general possible to set the alignment of such a record to one, so the 5342pragma is ignored in this case (with a warning). 5343 5344Specifying SPACE also disables alignment promotions for standalone objects, 5345which occur when the compiler increases the alignment of a specific object 5346without changing the alignment of its type. 5347 5348Specifying TIME causes larger default alignments to be chosen in the case of 5349small types with sizes that are not a power of 2. For example, consider: 5350 5351@example 5352type R is record 5353 A : Character; 5354 B : Character; 5355 C : Boolean; 5356end record; 5357 5358pragma Pack (R); 5359for R'Size use 17; 5360@end example 5361 5362The default alignment for this record is normally 1, but if this type is 5363compiled in @cite{Optimize_Alignment (Time)} mode, then the alignment is set 5364to 4, which wastes space for objects of the type, since they are now 4 bytes 5365long, but results in more efficient access when the whole record is referenced. 5366 5367As noted above, this is a configuration pragma, and there is a requirement 5368that all units in a partition be compiled with a consistent setting of the 5369optimization setting. This would normally be achieved by use of a configuration 5370pragma file containing the appropriate setting. The exception to this rule is 5371that units with an explicit configuration pragma in the same file as the source 5372unit are excluded from the consistency check, as are all predefined units. The 5373latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5374pragma appears at the start of the file. 5375 5376@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5377@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{90} 5378@section Pragma Ordered 5379 5380 5381Syntax: 5382 5383@example 5384pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5385@end example 5386 5387Most enumeration types are from a conceptual point of view unordered. 5388For example, consider: 5389 5390@example 5391type Color is (Red, Blue, Green, Yellow); 5392@end example 5393 5394By Ada semantics @cite{Blue > Red} and @cite{Green > Blue}, 5395but really these relations make no sense; the enumeration type merely 5396specifies a set of possible colors, and the order is unimportant. 5397 5398For unordered enumeration types, it is generally a good idea if 5399clients avoid comparisons (other than equality or inequality) and 5400explicit ranges. (A @emph{client} is a unit where the type is referenced, 5401other than the unit where the type is declared, its body, and its subunits.) 5402For example, if code buried in some client says: 5403 5404@example 5405if Current_Color < Yellow then ... 5406if Current_Color in Blue .. Green then ... 5407@end example 5408 5409then the client code is relying on the order, which is undesirable. 5410It makes the code hard to read and creates maintenance difficulties if 5411entries have to be added to the enumeration type. Instead, 5412the code in the client should list the possibilities, or an 5413appropriate subtype should be declared in the unit that declares 5414the original enumeration type. E.g., the following subtype could 5415be declared along with the type @cite{Color}: 5416 5417@example 5418subtype RBG is Color range Red .. Green; 5419@end example 5420 5421and then the client could write: 5422 5423@example 5424if Current_Color in RBG then ... 5425if Current_Color = Blue or Current_Color = Green then ... 5426@end example 5427 5428However, some enumeration types are legitimately ordered from a conceptual 5429point of view. For example, if you declare: 5430 5431@example 5432type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5433@end example 5434 5435then the ordering imposed by the language is reasonable, and 5436clients can depend on it, writing for example: 5437 5438@example 5439if D in Mon .. Fri then ... 5440if D < Wed then ... 5441@end example 5442 5443The pragma @emph{Ordered} is provided to mark enumeration types that 5444are conceptually ordered, alerting the reader that clients may depend 5445on the ordering. GNAT provides a pragma to mark enumerations as ordered 5446rather than one to mark them as unordered, since in our experience, 5447the great majority of enumeration types are conceptually unordered. 5448 5449The types @cite{Boolean}, @cite{Character}, @cite{Wide_Character}, 5450and @cite{Wide_Wide_Character} 5451are considered to be ordered types, so each is declared with a 5452pragma @cite{Ordered} in package @cite{Standard}. 5453 5454Normally pragma @cite{Ordered} serves only as documentation and a guide for 5455coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 5456requests warnings for inappropriate uses (comparisons and explicit 5457subranges) for unordered types. If this switch is used, then any 5458enumeration type not marked with pragma @cite{Ordered} will be considered 5459as unordered, and will generate warnings for inappropriate uses. 5460 5461Note that generic types are not considered ordered or unordered (since the 5462template can be instantiated for both cases), so we never generate warnings 5463for the case of generic enumerated types. 5464 5465For additional information please refer to the description of the 5466@emph{-gnatw.u} switch in the GNAT User's Guide. 5467 5468@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 5469@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{91} 5470@section Pragma Overflow_Mode 5471 5472 5473Syntax: 5474 5475@example 5476pragma Overflow_Mode 5477 ( [General =>] MODE 5478 [,[Assertions =>] MODE]); 5479 5480MODE ::= STRICT | MINIMIZED | ELIMINATED 5481@end example 5482 5483This pragma sets the current overflow mode to the given setting. For details 5484of the meaning of these modes, please refer to the 5485'Overflow Check Handling in GNAT' appendix in the 5486GNAT User's Guide. If only the @cite{General} parameter is present, 5487the given mode applies to all expressions. If both parameters are present, 5488the @cite{General} mode applies to expressions outside assertions, and 5489the @cite{Eliminated} mode applies to expressions within assertions. 5490 5491The case of the @cite{MODE} parameter is ignored, 5492so @cite{MINIMIZED}, @cite{Minimized} and 5493@cite{minimized} all have the same effect. 5494 5495The @cite{Overflow_Mode} pragma has the same scoping and placement 5496rules as pragma @cite{Suppress}, so it can occur either as a 5497configuration pragma, specifying a default for the whole 5498program, or in a declarative scope, where it applies to the 5499remaining declarations and statements in that scope. 5500 5501The pragma @cite{Suppress (Overflow_Check)} suppresses 5502overflow checking, but does not affect the overflow mode. 5503 5504The pragma @cite{Unsuppress (Overflow_Check)} unsuppresses (enables) 5505overflow checking, but does not affect the overflow mode. 5506 5507@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 5508@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{92} 5509@section Pragma Overriding_Renamings 5510 5511 5512@geindex Rational profile 5513 5514@geindex Rational compatibility 5515 5516Syntax: 5517 5518@example 5519pragma Overriding_Renamings; 5520@end example 5521 5522This is a GNAT configuration pragma to simplify porting 5523legacy code accepted by the Rational 5524Ada compiler. In the presence of this pragma, a renaming declaration that 5525renames an inherited operation declared in the same scope is legal if selected 5526notation is used as in: 5527 5528@example 5529pragma Overriding_Renamings; 5530... 5531package R is 5532 function F (..); 5533 ... 5534 function F (..) renames R.F; 5535end R; 5536@end example 5537 5538even though 5539RM 8.3 (15) stipulates that an overridden operation is not visible within the 5540declaration of the overriding operation. 5541 5542@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 5543@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{93} 5544@section Pragma Partition_Elaboration_Policy 5545 5546 5547Syntax: 5548 5549@example 5550pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 5551 5552POLICY_IDENTIFIER ::= Concurrent | Sequential 5553@end example 5554 5555This pragma is standard in Ada 2005, but is available in all earlier 5556versions of Ada as an implementation-defined pragma. 5557See Ada 2012 Reference Manual for details. 5558 5559@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 5560@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{94} 5561@section Pragma Part_Of 5562 5563 5564Syntax: 5565 5566@example 5567pragma Part_Of (ABSTRACT_STATE); 5568 5569ABSTRACT_STATE ::= NAME 5570@end example 5571 5572For the semantics of this pragma, see the entry for aspect @cite{Part_Of} in the 5573SPARK 2014 Reference Manual, section 7.2.6. 5574 5575@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 5576@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{95} 5577@section Pragma Passive 5578 5579 5580Syntax: 5581 5582@example 5583pragma Passive [(Semaphore | No)]; 5584@end example 5585 5586Syntax checked, but otherwise ignored by GNAT. This is recognized for 5587compatibility with DEC Ada 83 implementations, where it is used within a 5588task definition to request that a task be made passive. If the argument 5589@cite{Semaphore} is present, or the argument is omitted, then DEC Ada 83 5590treats the pragma as an assertion that the containing task is passive 5591and that optimization of context switch with this task is permitted and 5592desired. If the argument @cite{No} is present, the task must not be 5593optimized. GNAT does not attempt to optimize any tasks in this manner 5594(since protected objects are available in place of passive tasks). 5595 5596For more information on the subject of passive tasks, see the section 5597'Passive Task Optimization' in the GNAT Users Guide. 5598 5599@node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas 5600@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{96} 5601@section Pragma Persistent_BSS 5602 5603 5604Syntax: 5605 5606@example 5607pragma Persistent_BSS [(LOCAL_NAME)] 5608@end example 5609 5610This pragma allows selected objects to be placed in the @cite{.persistent_bss} 5611section. On some targets the linker and loader provide for special 5612treatment of this section, allowing a program to be reloaded without 5613affecting the contents of this data (hence the name persistent). 5614 5615There are two forms of usage. If an argument is given, it must be the 5616local name of a library level object, with no explicit initialization 5617and whose type is potentially persistent. If no argument is given, then 5618the pragma is a configuration pragma, and applies to all library level 5619objects with no explicit initialization of potentially persistent types. 5620 5621A potentially persistent type is a scalar type, or an untagged, 5622non-discriminated record, all of whose components have no explicit 5623initialization and are themselves of a potentially persistent type, 5624or an array, all of whose constraints are static, and whose component 5625type is potentially persistent. 5626 5627If this pragma is used on a target where this feature is not supported, 5628then the pragma will be ignored. See also @cite{pragma Linker_Section}. 5629 5630@node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas 5631@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{97} 5632@section Pragma Polling 5633 5634 5635Syntax: 5636 5637@example 5638pragma Polling (ON | OFF); 5639@end example 5640 5641This pragma controls the generation of polling code. This is normally off. 5642If @cite{pragma Polling (ON)} is used then periodic calls are generated to 5643the routine @cite{Ada.Exceptions.Poll}. This routine is a separate unit in the 5644runtime library, and can be found in file @code{a-excpol.adb}. 5645 5646Pragma @cite{Polling} can appear as a configuration pragma (for example it 5647can be placed in the @code{gnat.adc} file) to enable polling globally, or it 5648can be used in the statement or declaration sequence to control polling 5649more locally. 5650 5651A call to the polling routine is generated at the start of every loop and 5652at the start of every subprogram call. This guarantees that the @cite{Poll} 5653routine is called frequently, and places an upper bound (determined by 5654the complexity of the code) on the period between two @cite{Poll} calls. 5655 5656The primary purpose of the polling interface is to enable asynchronous 5657aborts on targets that cannot otherwise support it (for example Windows 5658NT), but it may be used for any other purpose requiring periodic polling. 5659The standard version is null, and can be replaced by a user program. This 5660will require re-compilation of the @cite{Ada.Exceptions} package that can 5661be found in files @code{a-except.ads} and @code{a-except.adb}. 5662 5663A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT 5664distribution) is used to enable the asynchronous abort capability on 5665targets that do not normally support the capability. The version of 5666@cite{Poll} in this file makes a call to the appropriate runtime routine 5667to test for an abort condition. 5668 5669Note that polling can also be enabled by use of the @emph{-gnatP} switch. 5670See the section on switches for gcc in the @cite{GNAT User's Guide}. 5671 5672@node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas 5673@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{98} 5674@section Pragma Post 5675 5676 5677@geindex Post 5678 5679@geindex Checks 5680@geindex postconditions 5681 5682Syntax: 5683 5684@example 5685pragma Post (Boolean_Expression); 5686@end example 5687 5688The @cite{Post} pragma is intended to be an exact replacement for 5689the language-defined 5690@cite{Post} aspect, and shares its restrictions and semantics. 5691It must appear either immediately following the corresponding 5692subprogram declaration (only other pragmas may intervene), or 5693if there is no separate subprogram declaration, then it can 5694appear at the start of the declarations in a subprogram body 5695(preceded only by other pragmas). 5696 5697@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 5698@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{99} 5699@section Pragma Postcondition 5700 5701 5702@geindex Postcondition 5703 5704@geindex Checks 5705@geindex postconditions 5706 5707Syntax: 5708 5709@example 5710pragma Postcondition ( 5711 [Check =>] Boolean_Expression 5712 [,[Message =>] String_Expression]); 5713@end example 5714 5715The @cite{Postcondition} pragma allows specification of automatic 5716postcondition checks for subprograms. These checks are similar to 5717assertions, but are automatically inserted just prior to the return 5718statements of the subprogram with which they are associated (including 5719implicit returns at the end of procedure bodies and associated 5720exception handlers). 5721 5722In addition, the boolean expression which is the condition which 5723must be true may contain references to function'Result in the case 5724of a function to refer to the returned value. 5725 5726@cite{Postcondition} pragmas may appear either immediately following the 5727(separate) declaration of a subprogram, or at the start of the 5728declarations of a subprogram body. Only other pragmas may intervene 5729(that is appear between the subprogram declaration and its 5730postconditions, or appear before the postcondition in the 5731declaration sequence in a subprogram body). In the case of a 5732postcondition appearing after a subprogram declaration, the 5733formal arguments of the subprogram are visible, and can be 5734referenced in the postcondition expressions. 5735 5736The postconditions are collected and automatically tested just 5737before any return (implicit or explicit) in the subprogram body. 5738A postcondition is only recognized if postconditions are active 5739at the time the pragma is encountered. The compiler switch @emph{gnata} 5740turns on all postconditions by default, and pragma @cite{Check_Policy} 5741with an identifier of @cite{Postcondition} can also be used to 5742control whether postconditions are active. 5743 5744The general approach is that postconditions are placed in the spec 5745if they represent functional aspects which make sense to the client. 5746For example we might have: 5747 5748@example 5749function Direction return Integer; 5750pragma Postcondition 5751 (Direction'Result = +1 5752 or else 5753 Direction'Result = -1); 5754@end example 5755 5756which serves to document that the result must be +1 or -1, and 5757will test that this is the case at run time if postcondition 5758checking is active. 5759 5760Postconditions within the subprogram body can be used to 5761check that some internal aspect of the implementation, 5762not visible to the client, is operating as expected. 5763For instance if a square root routine keeps an internal 5764counter of the number of times it is called, then we 5765might have the following postcondition: 5766 5767@example 5768Sqrt_Calls : Natural := 0; 5769 5770function Sqrt (Arg : Float) return Float is 5771 pragma Postcondition 5772 (Sqrt_Calls = Sqrt_Calls'Old + 1); 5773 ... 5774end Sqrt 5775@end example 5776 5777As this example, shows, the use of the @cite{Old} attribute 5778is often useful in postconditions to refer to the state on 5779entry to the subprogram. 5780 5781Note that postconditions are only checked on normal returns 5782from the subprogram. If an abnormal return results from 5783raising an exception, then the postconditions are not checked. 5784 5785If a postcondition fails, then the exception 5786@cite{System.Assertions.Assert_Failure} is raised. If 5787a message argument was supplied, then the given string 5788will be used as the exception message. If no message 5789argument was supplied, then the default message has 5790the form "Postcondition failed at file_name:line". The 5791exception is raised in the context of the subprogram 5792body, so it is possible to catch postcondition failures 5793within the subprogram body itself. 5794 5795Within a package spec, normal visibility rules 5796in Ada would prevent forward references within a 5797postcondition pragma to functions defined later in 5798the same package. This would introduce undesirable 5799ordering constraints. To avoid this problem, all 5800postcondition pragmas are analyzed at the end of 5801the package spec, allowing forward references. 5802 5803The following example shows that this even allows 5804mutually recursive postconditions as in: 5805 5806@example 5807package Parity_Functions is 5808 function Odd (X : Natural) return Boolean; 5809 pragma Postcondition 5810 (Odd'Result = 5811 (x = 1 5812 or else 5813 (x /= 0 and then Even (X - 1)))); 5814 5815 function Even (X : Natural) return Boolean; 5816 pragma Postcondition 5817 (Even'Result = 5818 (x = 0 5819 or else 5820 (x /= 1 and then Odd (X - 1)))); 5821 5822end Parity_Functions; 5823@end example 5824 5825There are no restrictions on the complexity or form of 5826conditions used within @cite{Postcondition} pragmas. 5827The following example shows that it is even possible 5828to verify performance behavior. 5829 5830@example 5831package Sort is 5832 5833 Performance : constant Float; 5834 -- Performance constant set by implementation 5835 -- to match target architecture behavior. 5836 5837 procedure Treesort (Arg : String); 5838 -- Sorts characters of argument using N*logN sort 5839 pragma Postcondition 5840 (Float (Clock - Clock'Old) <= 5841 Float (Arg'Length) * 5842 log (Float (Arg'Length)) * 5843 Performance); 5844end Sort; 5845@end example 5846 5847Note: postcondition pragmas associated with subprograms that are 5848marked as Inline_Always, or those marked as Inline with front-end 5849inlining (-gnatN option set) are accepted and legality-checked 5850by the compiler, but are ignored at run-time even if postcondition 5851checking is enabled. 5852 5853Note that pragma @cite{Postcondition} differs from the language-defined 5854@cite{Post} aspect (and corresponding @cite{Post} pragma) in allowing 5855multiple occurrences, allowing occurences in the body even if there 5856is a separate spec, and allowing a second string parameter, and the 5857use of the pragma identifier @cite{Check}. Historically, pragma 5858@cite{Postcondition} was implemented prior to the development of 5859Ada 2012, and has been retained in its original form for 5860compatibility purposes. 5861 5862@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas 5863@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{9a} 5864@section Pragma Post_Class 5865 5866 5867@geindex Post 5868 5869@geindex Checks 5870@geindex postconditions 5871 5872Syntax: 5873 5874@example 5875pragma Post_Class (Boolean_Expression); 5876@end example 5877 5878The @cite{Post_Class} pragma is intended to be an exact replacement for 5879the language-defined 5880@cite{Post'Class} aspect, and shares its restrictions and semantics. 5881It must appear either immediately following the corresponding 5882subprogram declaration (only other pragmas may intervene), or 5883if there is no separate subprogram declaration, then it can 5884appear at the start of the declarations in a subprogram body 5885(preceded only by other pragmas). 5886 5887Note: This pragma is called @cite{Post_Class} rather than 5888@cite{Post'Class} because the latter would not be strictly 5889conforming to the allowed syntax for pragmas. The motivation 5890for provinding pragmas equivalent to the aspects is to allow a program 5891to be written using the pragmas, and then compiled if necessary 5892using an Ada compiler that does not recognize the pragmas or 5893aspects, but is prepared to ignore the pragmas. The assertion 5894policy that controls this pragma is @cite{Post'Class}, not 5895@cite{Post_Class}. 5896 5897@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas 5898@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{9b} 5899@section Pragma Pre 5900 5901 5902@geindex Pre 5903 5904@geindex Checks 5905@geindex preconditions 5906 5907Syntax: 5908 5909@example 5910pragma Pre (Boolean_Expression); 5911@end example 5912 5913The @cite{Pre} pragma is intended to be an exact replacement for 5914the language-defined 5915@cite{Pre} aspect, and shares its restrictions and semantics. 5916It must appear either immediately following the corresponding 5917subprogram declaration (only other pragmas may intervene), or 5918if there is no separate subprogram declaration, then it can 5919appear at the start of the declarations in a subprogram body 5920(preceded only by other pragmas). 5921 5922@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 5923@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{9c} 5924@section Pragma Precondition 5925 5926 5927@geindex Preconditions 5928 5929@geindex Checks 5930@geindex preconditions 5931 5932Syntax: 5933 5934@example 5935pragma Precondition ( 5936 [Check =>] Boolean_Expression 5937 [,[Message =>] String_Expression]); 5938@end example 5939 5940The @cite{Precondition} pragma is similar to @cite{Postcondition} 5941except that the corresponding checks take place immediately upon 5942entry to the subprogram, and if a precondition fails, the exception 5943is raised in the context of the caller, and the attribute 'Result 5944cannot be used within the precondition expression. 5945 5946Otherwise, the placement and visibility rules are identical to those 5947described for postconditions. The following is an example of use 5948within a package spec: 5949 5950@example 5951package Math_Functions is 5952 ... 5953 function Sqrt (Arg : Float) return Float; 5954 pragma Precondition (Arg >= 0.0) 5955 ... 5956end Math_Functions; 5957@end example 5958 5959@cite{Precondition} pragmas may appear either immediately following the 5960(separate) declaration of a subprogram, or at the start of the 5961declarations of a subprogram body. Only other pragmas may intervene 5962(that is appear between the subprogram declaration and its 5963postconditions, or appear before the postcondition in the 5964declaration sequence in a subprogram body). 5965 5966Note: precondition pragmas associated with subprograms that are 5967marked as Inline_Always, or those marked as Inline with front-end 5968inlining (-gnatN option set) are accepted and legality-checked 5969by the compiler, but are ignored at run-time even if precondition 5970checking is enabled. 5971 5972Note that pragma @cite{Precondition} differs from the language-defined 5973@cite{Pre} aspect (and corresponding @cite{Pre} pragma) in allowing 5974multiple occurrences, allowing occurences in the body even if there 5975is a separate spec, and allowing a second string parameter, and the 5976use of the pragma identifier @cite{Check}. Historically, pragma 5977@cite{Precondition} was implemented prior to the development of 5978Ada 2012, and has been retained in its original form for 5979compatibility purposes. 5980 5981@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 5982@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{9d} 5983@section Pragma Predicate 5984 5985 5986Syntax: 5987 5988@example 5989pragma Predicate 5990 ([Entity =>] type_LOCAL_NAME, 5991 [Check =>] EXPRESSION); 5992@end example 5993 5994This pragma (available in all versions of Ada in GNAT) encompasses both 5995the @cite{Static_Predicate} and @cite{Dynamic_Predicate} aspects in 5996Ada 2012. A predicate is regarded as static if it has an allowed form 5997for @cite{Static_Predicate} and is otherwise treated as a 5998@cite{Dynamic_Predicate}. Otherwise, predicates specified by this 5999pragma behave exactly as described in the Ada 2012 reference manual. 6000For example, if we have 6001 6002@example 6003type R is range 1 .. 10; 6004subtype S is R; 6005pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6006subtype Q is R 6007pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6008@end example 6009 6010the effect is identical to the following Ada 2012 code: 6011 6012@example 6013type R is range 1 .. 10; 6014subtype S is R with 6015 Static_Predicate => S not in 4 .. 6; 6016subtype Q is R with 6017 Dynamic_Predicate => F(Q) or G(Q); 6018@end example 6019 6020Note that there are no pragmas @cite{Dynamic_Predicate} 6021or @cite{Static_Predicate}. That is 6022because these pragmas would affect legality and semantics of 6023the program and thus do not have a neutral effect if ignored. 6024The motivation behind providing pragmas equivalent to 6025corresponding aspects is to allow a program to be written 6026using the pragmas, and then compiled with a compiler that 6027will ignore the pragmas. That doesn't work in the case of 6028static and dynamic predicates, since if the corresponding 6029pragmas are ignored, then the behavior of the program is 6030fundamentally changed (for example a membership test 6031@cite{A in B} would not take into account a predicate 6032defined for subtype B). When following this approach, the 6033use of predicates should be avoided. 6034 6035@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6036@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{9e} 6037@section Pragma Predicate_Failure 6038 6039 6040Syntax: 6041 6042@example 6043pragma Predicate_Failure 6044 ([Entity =>] type_LOCAL_NAME, 6045 [Message =>] String_Expression); 6046@end example 6047 6048The @cite{Predicate_Failure} pragma is intended to be an exact replacement for 6049the language-defined 6050@cite{Predicate_Failure} aspect, and shares its restrictions and semantics. 6051 6052@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6053@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{9f} 6054@section Pragma Preelaborable_Initialization 6055 6056 6057Syntax: 6058 6059@example 6060pragma Preelaborable_Initialization (DIRECT_NAME); 6061@end example 6062 6063This pragma is standard in Ada 2005, but is available in all earlier 6064versions of Ada as an implementation-defined pragma. 6065See Ada 2012 Reference Manual for details. 6066 6067@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6068@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{a0} 6069@section Pragma Prefix_Exception_Messages 6070 6071 6072@geindex Prefix_Exception_Messages 6073 6074@geindex exception 6075 6076@geindex Exception_Message 6077 6078Syntax: 6079 6080@example 6081pragma Prefix_Exception_Messages; 6082@end example 6083 6084This is an implementation-defined configuration pragma that affects the 6085behavior of raise statements with a message given as a static string 6086constant (typically a string literal). In such cases, the string will 6087be automatically prefixed by the name of the enclosing entity (giving 6088the package and subprogram containing the raise statement). This helps 6089to identify where messages are coming from, and this mode is automatic 6090for the run-time library. 6091 6092The pragma has no effect if the message is computed with an expression other 6093than a static string constant, since the assumption in this case is that 6094the program computes exactly the string it wants. If you still want the 6095prefixing in this case, you can always call 6096@cite{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6097 6098@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6099@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{a1} 6100@section Pragma Pre_Class 6101 6102 6103@geindex Pre_Class 6104 6105@geindex Checks 6106@geindex preconditions 6107 6108Syntax: 6109 6110@example 6111pragma Pre_Class (Boolean_Expression); 6112@end example 6113 6114The @cite{Pre_Class} pragma is intended to be an exact replacement for 6115the language-defined 6116@cite{Pre'Class} aspect, and shares its restrictions and semantics. 6117It must appear either immediately following the corresponding 6118subprogram declaration (only other pragmas may intervene), or 6119if there is no separate subprogram declaration, then it can 6120appear at the start of the declarations in a subprogram body 6121(preceded only by other pragmas). 6122 6123Note: This pragma is called @cite{Pre_Class} rather than 6124@cite{Pre'Class} because the latter would not be strictly 6125conforming to the allowed syntax for pragmas. The motivation 6126for providing pragmas equivalent to the aspects is to allow a program 6127to be written using the pragmas, and then compiled if necessary 6128using an Ada compiler that does not recognize the pragmas or 6129aspects, but is prepared to ignore the pragmas. The assertion 6130policy that controls this pragma is @cite{Pre'Class}, not 6131@cite{Pre_Class}. 6132 6133@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6134@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{a2} 6135@section Pragma Priority_Specific_Dispatching 6136 6137 6138Syntax: 6139 6140@example 6141pragma Priority_Specific_Dispatching ( 6142 POLICY_IDENTIFIER, 6143 first_priority_EXPRESSION, 6144 last_priority_EXPRESSION) 6145 6146POLICY_IDENTIFIER ::= 6147 EDF_Across_Priorities | 6148 FIFO_Within_Priorities | 6149 Non_Preemptive_Within_Priorities | 6150 Round_Robin_Within_Priorities 6151@end example 6152 6153This pragma is standard in Ada 2005, but is available in all earlier 6154versions of Ada as an implementation-defined pragma. 6155See Ada 2012 Reference Manual for details. 6156 6157@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6158@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{a3} 6159@section Pragma Profile 6160 6161 6162Syntax: 6163 6164@example 6165pragma Profile (Ravenscar | Restricted | Rational | GNAT_Extended_Ravenscar); 6166@end example 6167 6168This pragma is standard in Ada 2005, but is available in all earlier 6169versions of Ada as an implementation-defined pragma. This is a 6170configuration pragma that establishes a set of configuration pragmas 6171that depend on the argument. @cite{Ravenscar} is standard in Ada 2005. 6172The other possibilities (@cite{Restricted}, @cite{Rational}, @cite{GNAT_Extended_Ravenscar}) 6173are implementation-defined. The set of configuration pragmas 6174is defined in the following sections. 6175 6176 6177@itemize * 6178 6179@item 6180Pragma Profile (Ravenscar) 6181 6182The @cite{Ravenscar} profile is standard in Ada 2005, 6183but is available in all earlier 6184versions of Ada as an implementation-defined pragma. This profile 6185establishes the following set of configuration pragmas: 6186 6187 6188@itemize * 6189 6190@item 6191@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6192 6193[RM D.2.2] Tasks are dispatched following a preemptive 6194priority-ordered scheduling policy. 6195 6196@item 6197@code{Locking_Policy (Ceiling_Locking)} 6198 6199[RM D.3] While tasks and interrupts execute a protected action, they inherit 6200the ceiling priority of the corresponding protected object. 6201 6202@item 6203@code{Detect_Blocking} 6204 6205This pragma forces the detection of potentially blocking operations within a 6206protected operation, and to raise Program_Error if that happens. 6207@end itemize 6208 6209plus the following set of restrictions: 6210 6211 6212@itemize * 6213 6214@item 6215@code{Max_Entry_Queue_Length => 1} 6216 6217No task can be queued on a protected entry. 6218 6219@item 6220@code{Max_Protected_Entries => 1} 6221 6222@item 6223@code{Max_Task_Entries => 0} 6224 6225No rendezvous statements are allowed. 6226 6227@item 6228@code{No_Abort_Statements} 6229 6230@item 6231@code{No_Dynamic_Attachment} 6232 6233@item 6234@code{No_Dynamic_Priorities} 6235 6236@item 6237@code{No_Implicit_Heap_Allocations} 6238 6239@item 6240@code{No_Local_Protected_Objects} 6241 6242@item 6243@code{No_Local_Timing_Events} 6244 6245@item 6246@code{No_Protected_Type_Allocators} 6247 6248@item 6249@code{No_Relative_Delay} 6250 6251@item 6252@code{No_Requeue_Statements} 6253 6254@item 6255@code{No_Select_Statements} 6256 6257@item 6258@code{No_Specific_Termination_Handlers} 6259 6260@item 6261@code{No_Task_Allocators} 6262 6263@item 6264@code{No_Task_Hierarchy} 6265 6266@item 6267@code{No_Task_Termination} 6268 6269@item 6270@code{Simple_Barriers} 6271@end itemize 6272 6273The Ravenscar profile also includes the following restrictions that specify 6274that there are no semantic dependences on the corresponding predefined 6275packages: 6276 6277 6278@itemize * 6279 6280@item 6281@code{No_Dependence => Ada.Asynchronous_Task_Control} 6282 6283@item 6284@code{No_Dependence => Ada.Calendar} 6285 6286@item 6287@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6288 6289@item 6290@code{No_Dependence => Ada.Execution_Time.Timers} 6291 6292@item 6293@code{No_Dependence => Ada.Task_Attributes} 6294 6295@item 6296@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6297@end itemize 6298 6299This set of configuration pragmas and restrictions correspond to the 6300definition of the 'Ravenscar Profile' for limited tasking, devised and 6301published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6302A description is also available at 6303@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6304 6305The original definition of the profile was revised at subsequent IRTAW 6306meetings. It has been included in the ISO 6307@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6308and was made part of the Ada 2005 standard. 6309The formal definition given by 6310the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6311AI-305) available at 6312@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6313@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6314 6315The above set is a superset of the restrictions provided by pragma 6316@code{Profile (Restricted)}, it includes six additional restrictions 6317(@code{Simple_Barriers}, @code{No_Select_Statements}, 6318@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6319@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6320that pragma @code{Profile (Ravenscar)}, like the pragma 6321@code{Profile (Restricted)}, 6322automatically causes the use of a simplified, 6323more efficient version of the tasking run-time library. 6324 6325@item 6326Pragma Profile (GNAT_Extended_Ravenscar) 6327 6328This profile corresponds to a GNAT specific extension of the 6329Ravenscar profile. The profile may change in the future although 6330only in a compatible way: some restrictions may be removed or 6331relaxed. It is defined as a variation of the Ravenscar profile. 6332 6333The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6334by @code{No_Implicit_Task_Allocations} and 6335@code{No_Implicit_Protected_Object_Allocations}. 6336 6337The @code{Simple_Barriers} restriction has been replaced by 6338@code{Pure_Barriers}. 6339 6340@item 6341Pragma Profile (Restricted) 6342 6343This profile corresponds to the GNAT restricted run time. It 6344establishes the following set of restrictions: 6345 6346 6347@itemize * 6348 6349@item 6350@code{No_Abort_Statements} 6351 6352@item 6353@code{No_Entry_Queue} 6354 6355@item 6356@code{No_Task_Hierarchy} 6357 6358@item 6359@code{No_Task_Allocators} 6360 6361@item 6362@code{No_Dynamic_Priorities} 6363 6364@item 6365@code{No_Terminate_Alternatives} 6366 6367@item 6368@code{No_Dynamic_Attachment} 6369 6370@item 6371@code{No_Protected_Type_Allocators} 6372 6373@item 6374@code{No_Local_Protected_Objects} 6375 6376@item 6377@code{No_Requeue_Statements} 6378 6379@item 6380@code{No_Task_Attributes_Package} 6381 6382@item 6383@code{Max_Asynchronous_Select_Nesting = 0} 6384 6385@item 6386@code{Max_Task_Entries = 0} 6387 6388@item 6389@code{Max_Protected_Entries = 1} 6390 6391@item 6392@code{Max_Select_Alternatives = 0} 6393@end itemize 6394 6395This set of restrictions causes the automatic selection of a simplified 6396version of the run time that provides improved performance for the 6397limited set of tasking functionality permitted by this set of restrictions. 6398 6399@item 6400Pragma Profile (Rational) 6401 6402The Rational profile is intended to facilitate porting legacy code that 6403compiles with the Rational APEX compiler, even when the code includes non- 6404conforming Ada constructs. The profile enables the following three pragmas: 6405 6406 6407@itemize * 6408 6409@item 6410@code{pragma Implicit_Packing} 6411 6412@item 6413@code{pragma Overriding_Renamings} 6414 6415@item 6416@code{pragma Use_VADS_Size} 6417@end itemize 6418@end itemize 6419 6420@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6421@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{a4} 6422@section Pragma Profile_Warnings 6423 6424 6425Syntax: 6426 6427@example 6428pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6429@end example 6430 6431This is an implementation-defined pragma that is similar in 6432effect to @cite{pragma Profile} except that instead of 6433generating @cite{Restrictions} pragmas, it generates 6434@cite{Restriction_Warnings} pragmas. The result is that 6435violations of the profile generate warning messages instead 6436of error messages. 6437 6438@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 6439@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{a5} 6440@section Pragma Propagate_Exceptions 6441 6442 6443@geindex Interfacing to C++ 6444 6445Syntax: 6446 6447@example 6448pragma Propagate_Exceptions; 6449@end example 6450 6451This pragma is now obsolete and, other than generating a warning if warnings 6452on obsolescent features are enabled, is ignored. 6453It is retained for compatibility 6454purposes. It used to be used in connection with optimization of 6455a now-obsolete mechanism for implementation of exceptions. 6456 6457@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 6458@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{a6} 6459@section Pragma Provide_Shift_Operators 6460 6461 6462@geindex Shift operators 6463 6464Syntax: 6465 6466@example 6467pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 6468@end example 6469 6470This pragma can be applied to a first subtype local name that specifies 6471either an unsigned or signed type. It has the effect of providing the 6472five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 6473Rotate_Left and Rotate_Right) for the given type. It is similar to 6474including the function declarations for these five operators, together 6475with the pragma Import (Intrinsic, ...) statements. 6476 6477@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 6478@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{a7} 6479@section Pragma Psect_Object 6480 6481 6482Syntax: 6483 6484@example 6485pragma Psect_Object ( 6486 [Internal =>] LOCAL_NAME, 6487 [, [External =>] EXTERNAL_SYMBOL] 6488 [, [Size =>] EXTERNAL_SYMBOL]); 6489 6490EXTERNAL_SYMBOL ::= 6491 IDENTIFIER 6492| static_string_EXPRESSION 6493@end example 6494 6495This pragma is identical in effect to pragma @cite{Common_Object}. 6496 6497@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 6498@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{a8} 6499@section Pragma Pure_Function 6500 6501 6502Syntax: 6503 6504@example 6505pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 6506@end example 6507 6508This pragma appears in the same declarative part as a function 6509declaration (or a set of function declarations if more than one 6510overloaded declaration exists, in which case the pragma applies 6511to all entities). It specifies that the function @cite{Entity} is 6512to be considered pure for the purposes of code generation. This means 6513that the compiler can assume that there are no side effects, and 6514in particular that two calls with identical arguments produce the 6515same result. It also means that the function can be used in an 6516address clause. 6517 6518Note that, quite deliberately, there are no static checks to try 6519to ensure that this promise is met, so @cite{Pure_Function} can be used 6520with functions that are conceptually pure, even if they do modify 6521global variables. For example, a square root function that is 6522instrumented to count the number of times it is called is still 6523conceptually pure, and can still be optimized, even though it 6524modifies a global variable (the count). Memo functions are another 6525example (where a table of previous calls is kept and consulted to 6526avoid re-computation). 6527 6528Note also that the normal rules excluding optimization of subprograms 6529in pure units (when parameter types are descended from System.Address, 6530or when the full view of a parameter type is limited), do not apply 6531for the Pure_Function case. If you explicitly specify Pure_Function, 6532the compiler may optimize away calls with identical arguments, and 6533if that results in unexpected behavior, the proper action is not to 6534use the pragma for subprograms that are not (conceptually) pure. 6535 6536Note: Most functions in a @cite{Pure} package are automatically pure, and 6537there is no need to use pragma @cite{Pure_Function} for such functions. One 6538exception is any function that has at least one formal of type 6539@cite{System.Address} or a type derived from it. Such functions are not 6540considered pure by default, since the compiler assumes that the 6541@cite{Address} parameter may be functioning as a pointer and that the 6542referenced data may change even if the address value does not. 6543Similarly, imported functions are not considered to be pure by default, 6544since there is no way of checking that they are in fact pure. The use 6545of pragma @cite{Pure_Function} for such a function will override these default 6546assumption, and cause the compiler to treat a designated subprogram as pure 6547in these cases. 6548 6549Note: If pragma @cite{Pure_Function} is applied to a renamed function, it 6550applies to the underlying renamed function. This can be used to 6551disambiguate cases of overloading where some but not all functions 6552in a set of overloaded functions are to be designated as pure. 6553 6554If pragma @cite{Pure_Function} is applied to a library level function, the 6555function is also considered pure from an optimization point of view, but the 6556unit is not a Pure unit in the categorization sense. So for example, a function 6557thus marked is free to @cite{with} non-pure units. 6558 6559@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 6560@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{a9} 6561@section Pragma Rational 6562 6563 6564Syntax: 6565 6566@example 6567pragma Rational; 6568@end example 6569 6570This pragma is considered obsolescent, but is retained for 6571compatibility purposes. It is equivalent to: 6572 6573@example 6574pragma Profile (Rational); 6575@end example 6576 6577@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 6578@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{aa} 6579@section Pragma Ravenscar 6580 6581 6582Syntax: 6583 6584@example 6585pragma Ravenscar; 6586@end example 6587 6588This pragma is considered obsolescent, but is retained for 6589compatibility purposes. It is equivalent to: 6590 6591@example 6592pragma Profile (Ravenscar); 6593@end example 6594 6595which is the preferred method of setting the @cite{Ravenscar} profile. 6596 6597@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 6598@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ab} 6599@section Pragma Refined_Depends 6600 6601 6602Syntax: 6603 6604@example 6605pragma Refined_Depends (DEPENDENCY_RELATION); 6606 6607DEPENDENCY_RELATION ::= 6608 null 6609 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 6610 6611DEPENDENCY_CLAUSE ::= 6612 OUTPUT_LIST =>[+] INPUT_LIST 6613 | NULL_DEPENDENCY_CLAUSE 6614 6615NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 6616 6617OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 6618 6619INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 6620 6621OUTPUT ::= NAME | FUNCTION_RESULT 6622INPUT ::= NAME 6623 6624where FUNCTION_RESULT is a function Result attribute_reference 6625@end example 6626 6627For the semantics of this pragma, see the entry for aspect @cite{Refined_Depends} in 6628the SPARK 2014 Reference Manual, section 6.1.5. 6629 6630@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 6631@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{ac} 6632@section Pragma Refined_Global 6633 6634 6635Syntax: 6636 6637@example 6638pragma Refined_Global (GLOBAL_SPECIFICATION); 6639 6640GLOBAL_SPECIFICATION ::= 6641 null 6642 | (GLOBAL_LIST) 6643 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 6644 6645MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 6646 6647MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 6648GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 6649GLOBAL_ITEM ::= NAME 6650@end example 6651 6652For the semantics of this pragma, see the entry for aspect @cite{Refined_Global} in 6653the SPARK 2014 Reference Manual, section 6.1.4. 6654 6655@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 6656@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{ad} 6657@section Pragma Refined_Post 6658 6659 6660Syntax: 6661 6662@example 6663pragma Refined_Post (boolean_EXPRESSION); 6664@end example 6665 6666For the semantics of this pragma, see the entry for aspect @cite{Refined_Post} in 6667the SPARK 2014 Reference Manual, section 7.2.7. 6668 6669@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 6670@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{ae} 6671@section Pragma Refined_State 6672 6673 6674Syntax: 6675 6676@example 6677pragma Refined_State (REFINEMENT_LIST); 6678 6679REFINEMENT_LIST ::= 6680 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 6681 6682REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 6683 6684CONSTITUENT_LIST ::= 6685 null 6686 | CONSTITUENT 6687 | (CONSTITUENT @{, CONSTITUENT@}) 6688 6689CONSTITUENT ::= object_NAME | state_NAME 6690@end example 6691 6692For the semantics of this pragma, see the entry for aspect @cite{Refined_State} in 6693the SPARK 2014 Reference Manual, section 7.2.2. 6694 6695@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 6696@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{af} 6697@section Pragma Relative_Deadline 6698 6699 6700Syntax: 6701 6702@example 6703pragma Relative_Deadline (time_span_EXPRESSION); 6704@end example 6705 6706This pragma is standard in Ada 2005, but is available in all earlier 6707versions of Ada as an implementation-defined pragma. 6708See Ada 2012 Reference Manual for details. 6709 6710@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas 6711@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{b0} 6712@section Pragma Remote_Access_Type 6713 6714 6715Syntax: 6716 6717@example 6718pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 6719@end example 6720 6721This pragma appears in the formal part of a generic declaration. 6722It specifies an exception to the RM rule from E.2.2(17/2), which forbids 6723the use of a remote access to class-wide type as actual for a formal 6724access type. 6725 6726When this pragma applies to a formal access type @cite{Entity}, that 6727type is treated as a remote access to class-wide type in the generic. 6728It must be a formal general access type, and its designated type must 6729be the class-wide type of a formal tagged limited private type from the 6730same generic declaration. 6731 6732In the generic unit, the formal type is subject to all restrictions 6733pertaining to remote access to class-wide types. At instantiation, the 6734actual type must be a remote access to class-wide type. 6735 6736@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas 6737@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{b1} 6738@section Pragma Restricted_Run_Time 6739 6740 6741Syntax: 6742 6743@example 6744pragma Restricted_Run_Time; 6745@end example 6746 6747This pragma is considered obsolescent, but is retained for 6748compatibility purposes. It is equivalent to: 6749 6750@example 6751pragma Profile (Restricted); 6752@end example 6753 6754which is the preferred method of setting the restricted run time 6755profile. 6756 6757@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 6758@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{b2} 6759@section Pragma Restriction_Warnings 6760 6761 6762Syntax: 6763 6764@example 6765pragma Restriction_Warnings 6766 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 6767@end example 6768 6769This pragma allows a series of restriction identifiers to be 6770specified (the list of allowed identifiers is the same as for 6771pragma @cite{Restrictions}). For each of these identifiers 6772the compiler checks for violations of the restriction, but 6773generates a warning message rather than an error message 6774if the restriction is violated. 6775 6776One use of this is in situations where you want to know 6777about violations of a restriction, but you want to ignore some of 6778these violations. Consider this example, where you want to set 6779Ada_95 mode and enable style checks, but you want to know about 6780any other use of implementation pragmas: 6781 6782@example 6783pragma Restriction_Warnings (No_Implementation_Pragmas); 6784pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 6785pragma Ada_95; 6786pragma Style_Checks ("2bfhkM160"); 6787pragma Warnings (On, "violation of No_Implementation_Pragmas"); 6788@end example 6789 6790By including the above lines in a configuration pragmas file, 6791the Ada_95 and Style_Checks pragmas are accepted without 6792generating a warning, but any other use of implementation 6793defined pragmas will cause a warning to be generated. 6794 6795@node Pragma Reviewable,Pragma Share_Generic,Pragma Restriction_Warnings,Implementation Defined Pragmas 6796@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{b3} 6797@section Pragma Reviewable 6798 6799 6800Syntax: 6801 6802@example 6803pragma Reviewable; 6804@end example 6805 6806This pragma is an RM-defined standard pragma, but has no effect on the 6807program being compiled, or on the code generated for the program. 6808 6809To obtain the required output specified in RM H.3.1, the compiler must be 6810run with various special switches as follows: 6811 6812 6813@itemize * 6814 6815@item 6816@emph{Where compiler-generated run-time checks remain} 6817 6818The switch @emph{-gnatGL} 6819may be used to list the expanded code in pseudo-Ada form. 6820Runtime checks show up in the listing either as explicit 6821checks or operators marked with @{@} to indicate a check is present. 6822 6823@item 6824@emph{An identification of known exceptions at compile time} 6825 6826If the program is compiled with @emph{-gnatwa}, 6827the compiler warning messages will indicate all cases where the compiler 6828detects that an exception is certain to occur at run time. 6829 6830@item 6831@emph{Possible reads of uninitialized variables} 6832 6833The compiler warns of many such cases, but its output is incomplete. 6834@end itemize 6835 6836 6837A supplemental static analysis tool 6838may be used to obtain a comprehensive list of all 6839possible points at which uninitialized data may be read. 6840 6841 6842@itemize * 6843 6844@item 6845@emph{Where run-time support routines are implicitly invoked} 6846 6847In the output from @emph{-gnatGL}, 6848run-time calls are explicitly listed as calls to the relevant 6849run-time routine. 6850 6851@item 6852@emph{Object code listing} 6853 6854This may be obtained either by using the @emph{-S} switch, 6855or the objdump utility. 6856 6857@item 6858@emph{Constructs known to be erroneous at compile time} 6859 6860These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 6861 6862@item 6863@emph{Stack usage information} 6864 6865Static stack usage data (maximum per-subprogram) can be obtained via the 6866@emph{-fstack-usage} switch to the compiler. 6867Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 6868to gnatbind 6869@end itemize 6870 6871 6872 6873@itemize * 6874 6875@item 6876@emph{Object code listing of entire partition} 6877 6878This can be obtained by compiling the partition with @emph{-S}, 6879or by applying objdump 6880to all the object files that are part of the partition. 6881 6882@item 6883@emph{A description of the run-time model} 6884 6885The full sources of the run-time are available, and the documentation of 6886these routines describes how these run-time routines interface to the 6887underlying operating system facilities. 6888 6889@item 6890@emph{Control and data-flow information} 6891@end itemize 6892 6893 6894A supplemental static analysis tool 6895may be used to obtain complete control and data-flow information, as well as 6896comprehensive messages identifying possible problems based on this 6897information. 6898 6899@node Pragma Share_Generic,Pragma Shared,Pragma Reviewable,Implementation Defined Pragmas 6900@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{b4} 6901@section Pragma Share_Generic 6902 6903 6904Syntax: 6905 6906@example 6907pragma Share_Generic (GNAME @{, GNAME@}); 6908 6909GNAME ::= generic_unit_NAME | generic_instance_NAME 6910@end example 6911 6912This pragma is provided for compatibility with Dec Ada 83. It has 6913no effect in @cite{GNAT} (which does not implement shared generics), other 6914than to check that the given names are all names of generic units or 6915generic instances. 6916 6917@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 6918@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{b5} 6919@section Pragma Shared 6920 6921 6922This pragma is provided for compatibility with Ada 83. The syntax and 6923semantics are identical to pragma Atomic. 6924 6925@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 6926@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{b6} 6927@section Pragma Short_Circuit_And_Or 6928 6929 6930Syntax: 6931 6932@example 6933pragma Short_Circuit_And_Or; 6934@end example 6935 6936This configuration pragma causes any occurrence of the AND operator applied to 6937operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 6938is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 6939may be useful in the context of certification protocols requiring the use of 6940short-circuited logical operators. If this configuration pragma occurs locally 6941within the file being compiled, it applies only to the file being compiled. 6942There is no requirement that all units in a partition use this option. 6943 6944@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 6945@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{b7} 6946@section Pragma Short_Descriptors 6947 6948 6949Syntax: 6950 6951@example 6952pragma Short_Descriptors 6953@end example 6954 6955This pragma is provided for compatibility with other Ada implementations. It 6956is recognized but ignored by all current versions of GNAT. 6957 6958@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 6959@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{b8} 6960@section Pragma Simple_Storage_Pool_Type 6961 6962 6963@geindex Storage pool 6964@geindex simple 6965 6966@geindex Simple storage pool 6967 6968Syntax: 6969 6970@example 6971pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 6972@end example 6973 6974A type can be established as a 'simple storage pool type' by applying 6975the representation pragma @cite{Simple_Storage_Pool_Type} to the type. 6976A type named in the pragma must be a library-level immutably limited record 6977type or limited tagged type declared immediately within a package declaration. 6978The type can also be a limited private type whose full type is allowed as 6979a simple storage pool type. 6980 6981For a simple storage pool type @cite{SSP}, nonabstract primitive subprograms 6982@cite{Allocate}, @cite{Deallocate}, and @cite{Storage_Size} can be declared that 6983are subtype conformant with the following subprogram declarations: 6984 6985@example 6986procedure Allocate 6987 (Pool : in out SSP; 6988 Storage_Address : out System.Address; 6989 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 6990 Alignment : System.Storage_Elements.Storage_Count); 6991 6992procedure Deallocate 6993 (Pool : in out SSP; 6994 Storage_Address : System.Address; 6995 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 6996 Alignment : System.Storage_Elements.Storage_Count); 6997 6998function Storage_Size (Pool : SSP) 6999 return System.Storage_Elements.Storage_Count; 7000@end example 7001 7002Procedure @cite{Allocate} must be declared, whereas @cite{Deallocate} and 7003@cite{Storage_Size} are optional. If @cite{Deallocate} is not declared, then 7004applying an unchecked deallocation has no effect other than to set its actual 7005parameter to null. If @cite{Storage_Size} is not declared, then the 7006@cite{Storage_Size} attribute applied to an access type associated with 7007a pool object of type SSP returns zero. Additional operations can be declared 7008for a simple storage pool type (such as for supporting a mark/release 7009storage-management discipline). 7010 7011An object of a simple storage pool type can be associated with an access 7012type by specifying the attribute 7013@ref{b9,,Simple_Storage_Pool}. For example: 7014 7015@example 7016My_Pool : My_Simple_Storage_Pool_Type; 7017 7018type Acc is access My_Data_Type; 7019 7020for Acc'Simple_Storage_Pool use My_Pool; 7021@end example 7022 7023See attribute @ref{b9,,Simple_Storage_Pool} 7024for further details. 7025 7026@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7027@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{ba}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{bb} 7028@section Pragma Source_File_Name 7029 7030 7031Syntax: 7032 7033@example 7034pragma Source_File_Name ( 7035 [Unit_Name =>] unit_NAME, 7036 Spec_File_Name => STRING_LITERAL, 7037 [Index => INTEGER_LITERAL]); 7038 7039pragma Source_File_Name ( 7040 [Unit_Name =>] unit_NAME, 7041 Body_File_Name => STRING_LITERAL, 7042 [Index => INTEGER_LITERAL]); 7043@end example 7044 7045Use this to override the normal naming convention. It is a configuration 7046pragma, and so has the usual applicability of configuration pragmas 7047(i.e., it applies to either an entire partition, or to all units in a 7048compilation, or to a single unit, depending on how it is used. 7049@cite{unit_name} is mapped to @cite{file_name_literal}. The identifier for 7050the second argument is required, and indicates whether this is the file 7051name for the spec or for the body. 7052 7053The optional Index argument should be used when a file contains multiple 7054units, and when you do not want to use @cite{gnatchop} to separate then 7055into multiple files (which is the recommended procedure to limit the 7056number of recompilations that are needed when some sources change). 7057For instance, if the source file @code{source.ada} contains 7058 7059@example 7060package B is 7061... 7062end B; 7063 7064with B; 7065procedure A is 7066begin 7067 .. 7068end A; 7069@end example 7070 7071you could use the following configuration pragmas: 7072 7073@example 7074pragma Source_File_Name 7075 (B, Spec_File_Name => "source.ada", Index => 1); 7076pragma Source_File_Name 7077 (A, Body_File_Name => "source.ada", Index => 2); 7078@end example 7079 7080Note that the @cite{gnatname} utility can also be used to generate those 7081configuration pragmas. 7082 7083Another form of the @cite{Source_File_Name} pragma allows 7084the specification of patterns defining alternative file naming schemes 7085to apply to all files. 7086 7087@example 7088pragma Source_File_Name 7089 ( [Spec_File_Name =>] STRING_LITERAL 7090 [,[Casing =>] CASING_SPEC] 7091 [,[Dot_Replacement =>] STRING_LITERAL]); 7092 7093pragma Source_File_Name 7094 ( [Body_File_Name =>] STRING_LITERAL 7095 [,[Casing =>] CASING_SPEC] 7096 [,[Dot_Replacement =>] STRING_LITERAL]); 7097 7098pragma Source_File_Name 7099 ( [Subunit_File_Name =>] STRING_LITERAL 7100 [,[Casing =>] CASING_SPEC] 7101 [,[Dot_Replacement =>] STRING_LITERAL]); 7102 7103CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7104@end example 7105 7106The first argument is a pattern that contains a single asterisk indicating 7107the point at which the unit name is to be inserted in the pattern string 7108to form the file name. The second argument is optional. If present it 7109specifies the casing of the unit name in the resulting file name string. 7110The default is lower case. Finally the third argument allows for systematic 7111replacement of any dots in the unit name by the specified string literal. 7112 7113Note that Source_File_Name pragmas should not be used if you are using 7114project files. The reason for this rule is that the project manager is not 7115aware of these pragmas, and so other tools that use the projet file would not 7116be aware of the intended naming conventions. If you are using project files, 7117file naming is controlled by Source_File_Name_Project pragmas, which are 7118usually supplied automatically by the project manager. A pragma 7119Source_File_Name cannot appear after a @ref{bc,,Pragma Source_File_Name_Project}. 7120 7121For more details on the use of the @cite{Source_File_Name} pragma, see the 7122sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}. 7123 7124@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7125@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{bd}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{bc} 7126@section Pragma Source_File_Name_Project 7127 7128 7129This pragma has the same syntax and semantics as pragma Source_File_Name. 7130It is only allowed as a stand-alone configuration pragma. 7131It cannot appear after a @ref{ba,,Pragma Source_File_Name}, and 7132most importantly, once pragma Source_File_Name_Project appears, 7133no further Source_File_Name pragmas are allowed. 7134 7135The intention is that Source_File_Name_Project pragmas are always 7136generated by the Project Manager in a manner consistent with the naming 7137specified in a project file, and when naming is controlled in this manner, 7138it is not permissible to attempt to modify this naming scheme using 7139Source_File_Name or Source_File_Name_Project pragmas (which would not be 7140known to the project manager). 7141 7142@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7143@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{be} 7144@section Pragma Source_Reference 7145 7146 7147Syntax: 7148 7149@example 7150pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7151@end example 7152 7153This pragma must appear as the first line of a source file. 7154@cite{integer_literal} is the logical line number of the line following 7155the pragma line (for use in error messages and debugging 7156information). @cite{string_literal} is a static string constant that 7157specifies the file name to be used in error messages and debugging 7158information. This is most notably used for the output of @cite{gnatchop} 7159with the @emph{-r} switch, to make sure that the original unchopped 7160source file is the one referred to. 7161 7162The second argument must be a string literal, it cannot be a static 7163string expression other than a string literal. This is because its value 7164is needed for error messages issued by all phases of the compiler. 7165 7166@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7167@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{bf} 7168@section Pragma SPARK_Mode 7169 7170 7171Syntax: 7172 7173@example 7174pragma SPARK_Mode [(On | Off)] ; 7175@end example 7176 7177In general a program can have some parts that are in SPARK 2014 (and 7178follow all the rules in the SPARK Reference Manual), and some parts 7179that are full Ada 2012. 7180 7181The SPARK_Mode pragma is used to identify which parts are in SPARK 71822014 (by default programs are in full Ada). The SPARK_Mode pragma can 7183be used in the following places: 7184 7185 7186@itemize * 7187 7188@item 7189As a configuration pragma, in which case it sets the default mode for 7190all units compiled with this pragma. 7191 7192@item 7193Immediately following a library-level subprogram spec 7194 7195@item 7196Immediately within a library-level package body 7197 7198@item 7199Immediately following the @cite{private} keyword of a library-level 7200package spec 7201 7202@item 7203Immediately following the @cite{begin} keyword of a library-level 7204package body 7205 7206@item 7207Immediately within a library-level subprogram body 7208@end itemize 7209 7210Normally a subprogram or package spec/body inherits the current mode 7211that is active at the point it is declared. But this can be overridden 7212by pragma within the spec or body as above. 7213 7214The basic consistency rule is that you can't turn SPARK_Mode back 7215@cite{On}, once you have explicitly (with a pragma) turned if 7216@cite{Off}. So the following rules apply: 7217 7218If a subprogram spec has SPARK_Mode @cite{Off}, then the body must 7219also have SPARK_Mode @cite{Off}. 7220 7221For a package, we have four parts: 7222 7223 7224@itemize * 7225 7226@item 7227the package public declarations 7228 7229@item 7230the package private part 7231 7232@item 7233the body of the package 7234 7235@item 7236the elaboration code after @cite{begin} 7237@end itemize 7238 7239For a package, the rule is that if you explicitly turn SPARK_Mode 7240@cite{Off} for any part, then all the following parts must have 7241SPARK_Mode @cite{Off}. Note that this may require repeating a pragma 7242SPARK_Mode (@cite{Off}) in the body. For example, if we have a 7243configuration pragma SPARK_Mode (@cite{On}) that turns the mode on by 7244default everywhere, and one particular package spec has pragma 7245SPARK_Mode (@cite{Off}), then that pragma will need to be repeated in 7246the package body. 7247 7248@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7249@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{c0} 7250@section Pragma Static_Elaboration_Desired 7251 7252 7253Syntax: 7254 7255@example 7256pragma Static_Elaboration_Desired; 7257@end example 7258 7259This pragma is used to indicate that the compiler should attempt to initialize 7260statically the objects declared in the library unit to which the pragma applies, 7261when these objects are initialized (explicitly or implicitly) by an aggregate. 7262In the absence of this pragma, aggregates in object declarations are expanded 7263into assignments and loops, even when the aggregate components are static 7264constants. When the aggregate is present the compiler builds a static expression 7265that requires no run-time code, so that the initialized object can be placed in 7266read-only data space. If the components are not static, or the aggregate has 7267more that 100 components, the compiler emits a warning that the pragma cannot 7268be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7269construction of larger aggregates with static components that include an others 7270choice.) 7271 7272@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7273@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{c1} 7274@section Pragma Stream_Convert 7275 7276 7277Syntax: 7278 7279@example 7280pragma Stream_Convert ( 7281 [Entity =>] type_LOCAL_NAME, 7282 [Read =>] function_NAME, 7283 [Write =>] function_NAME); 7284@end example 7285 7286This pragma provides an efficient way of providing user-defined stream 7287attributes. Not only is it simpler to use than specifying the attributes 7288directly, but more importantly, it allows the specification to be made in such 7289a way that the predefined unit Ada.Streams is not loaded unless it is actually 7290needed (i.e. unless the stream attributes are actually used); the use of 7291the Stream_Convert pragma adds no overhead at all, unless the stream 7292attributes are actually used on the designated type. 7293 7294The first argument specifies the type for which stream functions are 7295provided. The second parameter provides a function used to read values 7296of this type. It must name a function whose argument type may be any 7297subtype, and whose returned type must be the type given as the first 7298argument to the pragma. 7299 7300The meaning of the @cite{Read} parameter is that if a stream attribute directly 7301or indirectly specifies reading of the type given as the first parameter, 7302then a value of the type given as the argument to the Read function is 7303read from the stream, and then the Read function is used to convert this 7304to the required target type. 7305 7306Similarly the @cite{Write} parameter specifies how to treat write attributes 7307that directly or indirectly apply to the type given as the first parameter. 7308It must have an input parameter of the type specified by the first parameter, 7309and the return type must be the same as the input type of the Read function. 7310The effect is to first call the Write function to convert to the given stream 7311type, and then write the result type to the stream. 7312 7313The Read and Write functions must not be overloaded subprograms. If necessary 7314renamings can be supplied to meet this requirement. 7315The usage of this attribute is best illustrated by a simple example, taken 7316from the GNAT implementation of package Ada.Strings.Unbounded: 7317 7318@example 7319function To_Unbounded (S : String) return Unbounded_String 7320 renames To_Unbounded_String; 7321 7322pragma Stream_Convert 7323 (Unbounded_String, To_Unbounded, To_String); 7324@end example 7325 7326The specifications of the referenced functions, as given in the Ada 7327Reference Manual are: 7328 7329@example 7330function To_Unbounded_String (Source : String) 7331 return Unbounded_String; 7332 7333function To_String (Source : Unbounded_String) 7334 return String; 7335@end example 7336 7337The effect is that if the value of an unbounded string is written to a stream, 7338then the representation of the item in the stream is in the same format that 7339would be used for @cite{Standard.String'Output}, and this same representation 7340is expected when a value of this type is read from the stream. Note that the 7341value written always includes the bounds, even for Unbounded_String'Write, 7342since Unbounded_String is not an array type. 7343 7344Note that the @cite{Stream_Convert} pragma is not effective in the case of 7345a derived type of a non-limited tagged type. If such a type is specified then 7346the pragma is silently ignored, and the default implementation of the stream 7347attributes is used instead. 7348 7349@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7350@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{c2} 7351@section Pragma Style_Checks 7352 7353 7354Syntax: 7355 7356@example 7357pragma Style_Checks (string_LITERAL | ALL_CHECKS | 7358 On | Off [, LOCAL_NAME]); 7359@end example 7360 7361This pragma is used in conjunction with compiler switches to control the 7362built in style checking provided by GNAT. The compiler switches, if set, 7363provide an initial setting for the switches, and this pragma may be used 7364to modify these settings, or the settings may be provided entirely by 7365the use of the pragma. This pragma can be used anywhere that a pragma 7366is legal, including use as a configuration pragma (including use in 7367the @code{gnat.adc} file). 7368 7369The form with a string literal specifies which style options are to be 7370activated. These are additive, so they apply in addition to any previously 7371set style check options. The codes for the options are the same as those 7372used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 7373For example the following two methods can be used to enable 7374layout checking: 7375 7376 7377@itemize * 7378 7379@item 7380@example 7381pragma Style_Checks ("l"); 7382@end example 7383 7384@item 7385@example 7386gcc -c -gnatyl ... 7387@end example 7388@end itemize 7389 7390The form ALL_CHECKS activates all standard checks (its use is equivalent 7391to the use of the @cite{gnaty} switch with no options. 7392See the @cite{GNAT User's Guide} for details.) 7393 7394Note: the behavior is slightly different in GNAT mode (@emph{-gnatg} used). 7395In this case, ALL_CHECKS implies the standard set of GNAT mode style check 7396options (i.e. equivalent to @emph{-gnatyg}). 7397 7398The forms with @cite{Off} and @cite{On} 7399can be used to temporarily disable style checks 7400as shown in the following example: 7401 7402@example 7403pragma Style_Checks ("k"); -- requires keywords in lower case 7404pragma Style_Checks (Off); -- turn off style checks 7405NULL; -- this will not generate an error message 7406pragma Style_Checks (On); -- turn style checks back on 7407NULL; -- this will generate an error message 7408@end example 7409 7410Finally the two argument form is allowed only if the first argument is 7411@cite{On} or @cite{Off}. The effect is to turn of semantic style checks 7412for the specified entity, as shown in the following example: 7413 7414@example 7415pragma Style_Checks ("r"); -- require consistency of identifier casing 7416Arg : Integer; 7417Rf1 : Integer := ARG; -- incorrect, wrong case 7418pragma Style_Checks (Off, Arg); 7419Rf2 : Integer := ARG; -- OK, no error 7420@end example 7421 7422@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 7423@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{c3} 7424@section Pragma Subtitle 7425 7426 7427Syntax: 7428 7429@example 7430pragma Subtitle ([Subtitle =>] STRING_LITERAL); 7431@end example 7432 7433This pragma is recognized for compatibility with other Ada compilers 7434but is ignored by GNAT. 7435 7436@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 7437@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{c4} 7438@section Pragma Suppress 7439 7440 7441Syntax: 7442 7443@example 7444pragma Suppress (Identifier [, [On =>] Name]); 7445@end example 7446 7447This is a standard pragma, and supports all the check names required in 7448the RM. It is included here because GNAT recognizes some additional check 7449names that are implementation defined (as permitted by the RM): 7450 7451 7452@itemize * 7453 7454@item 7455@cite{Alignment_Check} can be used to suppress alignment checks 7456on addresses used in address clauses. Such checks can also be suppressed 7457by suppressing range checks, but the specific use of @cite{Alignment_Check} 7458allows suppression of alignment checks without suppressing other range checks. 7459Note that @cite{Alignment_Check} is suppressed by default on machines (such as 7460the x86) with non-strict alignment. 7461 7462@item 7463@cite{Atomic_Synchronization} can be used to suppress the special memory 7464synchronization instructions that are normally generated for access to 7465@cite{Atomic} variables to ensure correct synchronization between tasks 7466that use such variables for synchronization purposes. 7467 7468@item 7469@cite{Duplicated_Tag_Check} Can be used to suppress the check that is generated 7470for a duplicated tag value when a tagged type is declared. 7471 7472@item 7473@cite{Container_Checks} Can be used to suppress all checks within Ada.Containers 7474and instances of its children, including Tampering_Check. 7475 7476@item 7477@cite{Tampering_Check} Can be used to suppress tampering check in the containers. 7478 7479@item 7480@cite{Predicate_Check} can be used to control whether predicate checks are 7481active. It is applicable only to predicates for which the policy is 7482@cite{Check}. Unlike @cite{Assertion_Policy}, which determines if a given 7483predicate is ignored or checked for the whole program, the use of 7484@cite{Suppress} and @cite{Unsuppress} with this check name allows a given 7485predicate to be turned on and off at specific points in the program. 7486 7487@item 7488@cite{Validity_Check} can be used specifically to control validity checks. 7489If @cite{Suppress} is used to suppress validity checks, then no validity 7490checks are performed, including those specified by the appropriate compiler 7491switch or the @cite{Validity_Checks} pragma. 7492 7493@item 7494Additional check names previously introduced by use of the @cite{Check_Name} 7495pragma are also allowed. 7496@end itemize 7497 7498Note that pragma Suppress gives the compiler permission to omit 7499checks, but does not require the compiler to omit checks. The compiler 7500will generate checks if they are essentially free, even when they are 7501suppressed. In particular, if the compiler can prove that a certain 7502check will necessarily fail, it will generate code to do an 7503unconditional 'raise', even if checks are suppressed. The compiler 7504warns in this case. 7505 7506Of course, run-time checks are omitted whenever the compiler can prove 7507that they will not fail, whether or not checks are suppressed. 7508 7509@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 7510@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{c5} 7511@section Pragma Suppress_All 7512 7513 7514Syntax: 7515 7516@example 7517pragma Suppress_All; 7518@end example 7519 7520This pragma can appear anywhere within a unit. 7521The effect is to apply @cite{Suppress (All_Checks)} to the unit 7522in which it appears. This pragma is implemented for compatibility with DEC 7523Ada 83 usage where it appears at the end of a unit, and for compatibility 7524with Rational Ada, where it appears as a program unit pragma. 7525The use of the standard Ada pragma @cite{Suppress (All_Checks)} 7526as a normal configuration pragma is the preferred usage in GNAT. 7527 7528@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 7529@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{c6} 7530@section Pragma Suppress_Debug_Info 7531 7532 7533Syntax: 7534 7535@example 7536pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 7537@end example 7538 7539This pragma can be used to suppress generation of debug information 7540for the specified entity. It is intended primarily for use in debugging 7541the debugger, and navigating around debugger problems. 7542 7543@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 7544@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{c7} 7545@section Pragma Suppress_Exception_Locations 7546 7547 7548Syntax: 7549 7550@example 7551pragma Suppress_Exception_Locations; 7552@end example 7553 7554In normal mode, a raise statement for an exception by default generates 7555an exception message giving the file name and line number for the location 7556of the raise. This is useful for debugging and logging purposes, but this 7557entails extra space for the strings for the messages. The configuration 7558pragma @cite{Suppress_Exception_Locations} can be used to suppress the 7559generation of these strings, with the result that space is saved, but the 7560exception message for such raises is null. This configuration pragma may 7561appear in a global configuration pragma file, or in a specific unit as 7562usual. It is not required that this pragma be used consistently within 7563a partition, so it is fine to have some units within a partition compiled 7564with this pragma and others compiled in normal mode without it. 7565 7566@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 7567@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{c8} 7568@section Pragma Suppress_Initialization 7569 7570 7571@geindex Suppressing initialization 7572 7573@geindex Initialization 7574@geindex suppression of 7575 7576Syntax: 7577 7578@example 7579pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 7580@end example 7581 7582Here variable_or_subtype_Name is the name introduced by a type declaration 7583or subtype declaration or the name of a variable introduced by an 7584object declaration. 7585 7586In the case of a type or subtype 7587this pragma suppresses any implicit or explicit initialization 7588for all variables of the given type or subtype, 7589including initialization resulting from the use of pragmas 7590Normalize_Scalars or Initialize_Scalars. 7591 7592This is considered a representation item, so it cannot be given after 7593the type is frozen. It applies to all subsequent object declarations, 7594and also any allocator that creates objects of the type. 7595 7596If the pragma is given for the first subtype, then it is considered 7597to apply to the base type and all its subtypes. If the pragma is given 7598for other than a first subtype, then it applies only to the given subtype. 7599The pragma may not be given after the type is frozen. 7600 7601Note that this includes eliminating initialization of discriminants 7602for discriminated types, and tags for tagged types. In these cases, 7603you will have to use some non-portable mechanism (e.g. address 7604overlays or unchecked conversion) to achieve required initialization 7605of these fields before accessing any object of the corresponding type. 7606 7607For the variable case, implicit initialization for the named variable 7608is suppressed, just as though its subtype had been given in a pragma 7609Suppress_Initialization, as described above. 7610 7611@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 7612@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{c9} 7613@section Pragma Task_Name 7614 7615 7616Syntax 7617 7618@example 7619pragma Task_Name (string_EXPRESSION); 7620@end example 7621 7622This pragma appears within a task definition (like pragma 7623@cite{Priority}) and applies to the task in which it appears. The 7624argument must be of type String, and provides a name to be used for 7625the task instance when the task is created. Note that this expression 7626is not required to be static, and in particular, it can contain 7627references to task discriminants. This facility can be used to 7628provide different names for different tasks as they are created, 7629as illustrated in the example below. 7630 7631The task name is recorded internally in the run-time structures 7632and is accessible to tools like the debugger. In addition the 7633routine @cite{Ada.Task_Identification.Image} will return this 7634string, with a unique task address appended. 7635 7636@example 7637-- Example of the use of pragma Task_Name 7638 7639with Ada.Task_Identification; 7640use Ada.Task_Identification; 7641with Text_IO; use Text_IO; 7642procedure t3 is 7643 7644 type Astring is access String; 7645 7646 task type Task_Typ (Name : access String) is 7647 pragma Task_Name (Name.all); 7648 end Task_Typ; 7649 7650 task body Task_Typ is 7651 Nam : constant String := Image (Current_Task); 7652 begin 7653 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 7654 end Task_Typ; 7655 7656 type Ptr_Task is access Task_Typ; 7657 Task_Var : Ptr_Task; 7658 7659begin 7660 Task_Var := 7661 new Task_Typ (new String'("This is task 1")); 7662 Task_Var := 7663 new Task_Typ (new String'("This is task 2")); 7664end; 7665@end example 7666 7667@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 7668@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{ca} 7669@section Pragma Task_Storage 7670 7671 7672Syntax: 7673 7674@example 7675pragma Task_Storage ( 7676 [Task_Type =>] LOCAL_NAME, 7677 [Top_Guard =>] static_integer_EXPRESSION); 7678@end example 7679 7680This pragma specifies the length of the guard area for tasks. The guard 7681area is an additional storage area allocated to a task. A value of zero 7682means that either no guard area is created or a minimal guard area is 7683created, depending on the target. This pragma can appear anywhere a 7684@cite{Storage_Size} attribute definition clause is allowed for a task 7685type. 7686 7687@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 7688@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{cb} 7689@section Pragma Test_Case 7690 7691 7692@geindex Test cases 7693 7694Syntax: 7695 7696@example 7697pragma Test_Case ( 7698 [Name =>] static_string_Expression 7699 ,[Mode =>] (Nominal | Robustness) 7700 [, Requires => Boolean_Expression] 7701 [, Ensures => Boolean_Expression]); 7702@end example 7703 7704The @cite{Test_Case} pragma allows defining fine-grain specifications 7705for use by testing tools. 7706The compiler checks the validity of the @cite{Test_Case} pragma, but its 7707presence does not lead to any modification of the code generated by the 7708compiler. 7709 7710@cite{Test_Case} pragmas may only appear immediately following the 7711(separate) declaration of a subprogram in a package declaration, inside 7712a package spec unit. Only other pragmas may intervene (that is appear 7713between the subprogram declaration and a test case). 7714 7715The compiler checks that boolean expressions given in @cite{Requires} and 7716@cite{Ensures} are valid, where the rules for @cite{Requires} are the 7717same as the rule for an expression in @cite{Precondition} and the rules 7718for @cite{Ensures} are the same as the rule for an expression in 7719@cite{Postcondition}. In particular, attributes @cite{'Old} and 7720@cite{'Result} can only be used within the @cite{Ensures} 7721expression. The following is an example of use within a package spec: 7722 7723@example 7724package Math_Functions is 7725 ... 7726 function Sqrt (Arg : Float) return Float; 7727 pragma Test_Case (Name => "Test 1", 7728 Mode => Nominal, 7729 Requires => Arg < 10000, 7730 Ensures => Sqrt'Result < 10); 7731 ... 7732end Math_Functions; 7733@end example 7734 7735The meaning of a test case is that there is at least one context where 7736@cite{Requires} holds such that, if the associated subprogram is executed in 7737that context, then @cite{Ensures} holds when the subprogram returns. 7738Mode @cite{Nominal} indicates that the input context should also satisfy the 7739precondition of the subprogram, and the output context should also satisfy its 7740postcondition. Mode @cite{Robustness} indicates that the precondition and 7741postcondition of the subprogram should be ignored for this test case. 7742 7743@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 7744@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{cc} 7745@section Pragma Thread_Local_Storage 7746 7747 7748@geindex Task specific storage 7749 7750@geindex TLS (Thread Local Storage) 7751 7752@geindex Task_Attributes 7753 7754Syntax: 7755 7756@example 7757pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 7758@end example 7759 7760This pragma specifies that the specified entity, which must be 7761a variable declared in a library level package, is to be marked as 7762"Thread Local Storage" (@cite{TLS}). On systems supporting this (which 7763include Windows, Solaris, GNU/Linux and VxWorks 6), this causes each 7764thread (and hence each Ada task) to see a distinct copy of the variable. 7765 7766The variable may not have default initialization, and if there is 7767an explicit initialization, it must be either @cite{null} for an 7768access variable, or a static expression for a scalar variable. 7769This provides a low level mechanism similar to that provided by 7770the @cite{Ada.Task_Attributes} package, but much more efficient 7771and is also useful in writing interface code that will interact 7772with foreign threads. 7773 7774If this pragma is used on a system where @cite{TLS} is not supported, 7775then an error message will be generated and the program will be rejected. 7776 7777@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 7778@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{cd} 7779@section Pragma Time_Slice 7780 7781 7782Syntax: 7783 7784@example 7785pragma Time_Slice (static_duration_EXPRESSION); 7786@end example 7787 7788For implementations of GNAT on operating systems where it is possible 7789to supply a time slice value, this pragma may be used for this purpose. 7790It is ignored if it is used in a system that does not allow this control, 7791or if it appears in other than the main program unit. 7792 7793@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 7794@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{ce} 7795@section Pragma Title 7796 7797 7798Syntax: 7799 7800@example 7801pragma Title (TITLING_OPTION [, TITLING OPTION]); 7802 7803TITLING_OPTION ::= 7804 [Title =>] STRING_LITERAL, 7805| [Subtitle =>] STRING_LITERAL 7806@end example 7807 7808Syntax checked but otherwise ignored by GNAT. This is a listing control 7809pragma used in DEC Ada 83 implementations to provide a title and/or 7810subtitle for the program listing. The program listing generated by GNAT 7811does not have titles or subtitles. 7812 7813Unlike other pragmas, the full flexibility of named notation is allowed 7814for this pragma, i.e., the parameters may be given in any order if named 7815notation is used, and named and positional notation can be mixed 7816following the normal rules for procedure calls in Ada. 7817 7818@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 7819@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{cf} 7820@section Pragma Type_Invariant 7821 7822 7823Syntax: 7824 7825@example 7826pragma Type_Invariant 7827 ([Entity =>] type_LOCAL_NAME, 7828 [Check =>] EXPRESSION); 7829@end example 7830 7831The @cite{Type_Invariant} pragma is intended to be an exact 7832replacement for the language-defined @cite{Type_Invariant} 7833aspect, and shares its restrictions and semantics. It differs 7834from the language defined @cite{Invariant} pragma in that it 7835does not permit a string parameter, and it is 7836controlled by the assertion identifier @cite{Type_Invariant} 7837rather than @cite{Invariant}. 7838 7839@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 7840@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{d0} 7841@section Pragma Type_Invariant_Class 7842 7843 7844Syntax: 7845 7846@example 7847pragma Type_Invariant_Class 7848 ([Entity =>] type_LOCAL_NAME, 7849 [Check =>] EXPRESSION); 7850@end example 7851 7852The @cite{Type_Invariant_Class} pragma is intended to be an exact 7853replacement for the language-defined @cite{Type_Invariant'Class} 7854aspect, and shares its restrictions and semantics. 7855 7856Note: This pragma is called @cite{Type_Invariant_Class} rather than 7857@cite{Type_Invariant'Class} because the latter would not be strictly 7858conforming to the allowed syntax for pragmas. The motivation 7859for providing pragmas equivalent to the aspects is to allow a program 7860to be written using the pragmas, and then compiled if necessary 7861using an Ada compiler that does not recognize the pragmas or 7862aspects, but is prepared to ignore the pragmas. The assertion 7863policy that controls this pragma is @cite{Type_Invariant'Class}, 7864not @cite{Type_Invariant_Class}. 7865 7866@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 7867@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{d1} 7868@section Pragma Unchecked_Union 7869 7870 7871@geindex Unions in C 7872 7873Syntax: 7874 7875@example 7876pragma Unchecked_Union (first_subtype_LOCAL_NAME); 7877@end example 7878 7879This pragma is used to specify a representation of a record type that is 7880equivalent to a C union. It was introduced as a GNAT implementation defined 7881pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 7882pragma, making it language defined, and GNAT fully implements this extended 7883version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 7884details, consult the Ada 2012 Reference Manual, section B.3.3. 7885 7886@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 7887@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{d2} 7888@section Pragma Unevaluated_Use_Of_Old 7889 7890 7891@geindex Attribute Old 7892 7893@geindex Attribute Loop_Entry 7894 7895@geindex Unevaluated_Use_Of_Old 7896 7897Syntax: 7898 7899@example 7900pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 7901@end example 7902 7903This pragma controls the processing of attributes Old and Loop_Entry. 7904If either of these attributes is used in a potentially unevaluated 7905expression (e.g. the then or else parts of an if expression), then 7906normally this usage is considered illegal if the prefix of the attribute 7907is other than an entity name. The language requires this 7908behavior for Old, and GNAT copies the same rule for Loop_Entry. 7909 7910The reason for this rule is that otherwise, we can have a situation 7911where we save the Old value, and this results in an exception, even 7912though we might not evaluate the attribute. Consider this example: 7913 7914@example 7915package UnevalOld is 7916 K : Character; 7917 procedure U (A : String; C : Boolean) -- ERROR 7918 with Post => (if C then A(1)'Old = K else True); 7919end; 7920@end example 7921 7922If procedure U is called with a string with a lower bound of 2, and 7923C false, then an exception would be raised trying to evaluate A(1) 7924on entry even though the value would not be actually used. 7925 7926Although the rule guarantees against this possibility, it is sometimes 7927too restrictive. For example if we know that the string has a lower 7928bound of 1, then we will never raise an exception. 7929The pragma @cite{Unevaluated_Use_Of_Old} can be 7930used to modify this behavior. If the argument is @cite{Error} then an 7931error is given (this is the default RM behavior). If the argument is 7932@cite{Warn} then the usage is allowed as legal but with a warning 7933that an exception might be raised. If the argument is @cite{Allow} 7934then the usage is allowed as legal without generating a warning. 7935 7936This pragma may appear as a configuration pragma, or in a declarative 7937part or package specification. In the latter case it applies to 7938uses up to the end of the corresponding statement sequence or 7939sequence of package declarations. 7940 7941@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 7942@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{d3} 7943@section Pragma Unimplemented_Unit 7944 7945 7946Syntax: 7947 7948@example 7949pragma Unimplemented_Unit; 7950@end example 7951 7952If this pragma occurs in a unit that is processed by the compiler, GNAT 7953aborts with the message @code{xxx not implemented}, where 7954@cite{xxx} is the name of the current compilation unit. This pragma is 7955intended to allow the compiler to handle unimplemented library units in 7956a clean manner. 7957 7958The abort only happens if code is being generated. Thus you can use 7959specs of unimplemented packages in syntax or semantic checking mode. 7960 7961@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas 7962@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{d4} 7963@section Pragma Universal_Aliasing 7964 7965 7966Syntax: 7967 7968@example 7969pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 7970@end example 7971 7972@cite{type_LOCAL_NAME} must refer to a type declaration in the current 7973declarative part. The effect is to inhibit strict type-based aliasing 7974optimization for the given type. In other words, the effect is as though 7975access types designating this type were subject to pragma No_Strict_Aliasing. 7976For a detailed description of the strict aliasing optimization, and the 7977situations in which it must be suppressed, see the section on 7978@cite{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}. 7979 7980@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas 7981@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{d5} 7982@section Pragma Universal_Data 7983 7984 7985Syntax: 7986 7987@example 7988pragma Universal_Data [(library_unit_Name)]; 7989@end example 7990 7991This pragma is supported only for the AAMP target and is ignored for 7992other targets. The pragma specifies that all library-level objects 7993(Counter 0 data) associated with the library unit are to be accessed 7994and updated using universal addressing (24-bit addresses for AAMP5) 7995rather than the default of 16-bit Data Environment (DENV) addressing. 7996Use of this pragma will generally result in less efficient code for 7997references to global data associated with the library unit, but 7998allows such data to be located anywhere in memory. This pragma is 7999a library unit pragma, but can also be used as a configuration pragma 8000(including use in the @code{gnat.adc} file). The functionality 8001of this pragma is also available by applying the -univ switch on the 8002compilations of units where universal addressing of the data is desired. 8003 8004@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas 8005@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{d6} 8006@section Pragma Unmodified 8007 8008 8009@geindex Warnings 8010@geindex unmodified 8011 8012Syntax: 8013 8014@example 8015pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8016@end example 8017 8018This pragma signals that the assignable entities (variables, 8019@cite{out} parameters, @cite{in out} parameters) whose names are listed are 8020deliberately not assigned in the current source unit. This 8021suppresses warnings about the 8022entities being referenced but not assigned, and in addition a warning will be 8023generated if one of these entities is in fact assigned in the 8024same unit as the pragma (or in the corresponding body, or one 8025of its subunits). 8026 8027This is particularly useful for clearly signaling that a particular 8028parameter is not modified, even though the spec suggests that it might 8029be. 8030 8031For the variable case, warnings are never given for unreferenced variables 8032whose name contains one of the substrings 8033@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED} in any casing. Such names 8034are typically to be used in cases where such warnings are expected. 8035Thus it is never necessary to use @cite{pragma Unmodified} for such 8036variables, though it is harmless to do so. 8037 8038@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8039@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{d7} 8040@section Pragma Unreferenced 8041 8042 8043@geindex Warnings 8044@geindex unreferenced 8045 8046Syntax: 8047 8048@example 8049pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8050pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8051@end example 8052 8053This pragma signals that the entities whose names are listed are 8054deliberately not referenced in the current source unit after the 8055occurrence of the pragma. This 8056suppresses warnings about the 8057entities being unreferenced, and in addition a warning will be 8058generated if one of these entities is in fact subsequently referenced in the 8059same unit as the pragma (or in the corresponding body, or one 8060of its subunits). 8061 8062This is particularly useful for clearly signaling that a particular 8063parameter is not referenced in some particular subprogram implementation 8064and that this is deliberate. It can also be useful in the case of 8065objects declared only for their initialization or finalization side 8066effects. 8067 8068If @cite{LOCAL_NAME} identifies more than one matching homonym in the 8069current scope, then the entity most recently declared is the one to which 8070the pragma applies. Note that in the case of accept formals, the pragma 8071Unreferenced may appear immediately after the keyword @cite{do} which 8072allows the indication of whether or not accept formals are referenced 8073or not to be given individually for each accept statement. 8074 8075The left hand side of an assignment does not count as a reference for the 8076purpose of this pragma. Thus it is fine to assign to an entity for which 8077pragma Unreferenced is given. 8078 8079Note that if a warning is desired for all calls to a given subprogram, 8080regardless of whether they occur in the same unit as the subprogram 8081declaration, then this pragma should not be used (calls from another 8082unit would not be flagged); pragma Obsolescent can be used instead 8083for this purpose, see @ref{8d,,Pragma Obsolescent}. 8084 8085The second form of pragma @cite{Unreferenced} is used within a context 8086clause. In this case the arguments must be unit names of units previously 8087mentioned in @cite{with} clauses (similar to the usage of pragma 8088@cite{Elaborate_All}. The effect is to suppress warnings about unreferenced 8089units and unreferenced entities within these units. 8090 8091For the variable case, warnings are never given for unreferenced variables 8092whose name contains one of the substrings 8093@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED} in any casing. Such names 8094are typically to be used in cases where such warnings are expected. 8095Thus it is never necessary to use @cite{pragma Unreferenced} for such 8096variables, though it is harmless to do so. 8097 8098@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8099@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{d8} 8100@section Pragma Unreferenced_Objects 8101 8102 8103@geindex Warnings 8104@geindex unreferenced 8105 8106Syntax: 8107 8108@example 8109pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8110@end example 8111 8112This pragma signals that for the types or subtypes whose names are 8113listed, objects which are declared with one of these types or subtypes may 8114not be referenced, and if no references appear, no warnings are given. 8115 8116This is particularly useful for objects which are declared solely for their 8117initialization and finalization effect. Such variables are sometimes referred 8118to as RAII variables (Resource Acquisition Is Initialization). Using this 8119pragma on the relevant type (most typically a limited controlled type), the 8120compiler will automatically suppress unwanted warnings about these variables 8121not being referenced. 8122 8123@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8124@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{d9} 8125@section Pragma Unreserve_All_Interrupts 8126 8127 8128Syntax: 8129 8130@example 8131pragma Unreserve_All_Interrupts; 8132@end example 8133 8134Normally certain interrupts are reserved to the implementation. Any attempt 8135to attach an interrupt causes Program_Error to be raised, as described in 8136RM C.3.2(22). A typical example is the @cite{SIGINT} interrupt used in 8137many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8138reserved to the implementation, so that @code{Ctrl-C} can be used to 8139interrupt execution. 8140 8141If the pragma @cite{Unreserve_All_Interrupts} appears anywhere in any unit in 8142a program, then all such interrupts are unreserved. This allows the 8143program to handle these interrupts, but disables their standard 8144functions. For example, if this pragma is used, then pressing 8145@code{Ctrl-C} will not automatically interrupt execution. However, 8146a program can then handle the @cite{SIGINT} interrupt as it chooses. 8147 8148For a full list of the interrupts handled in a specific implementation, 8149see the source code for the spec of @cite{Ada.Interrupts.Names} in 8150file @code{a-intnam.ads}. This is a target dependent file that contains the 8151list of interrupts recognized for a given target. The documentation in 8152this file also specifies what interrupts are affected by the use of 8153the @cite{Unreserve_All_Interrupts} pragma. 8154 8155For a more general facility for controlling what interrupts can be 8156handled, see pragma @cite{Interrupt_State}, which subsumes the functionality 8157of the @cite{Unreserve_All_Interrupts} pragma. 8158 8159@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8160@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{da} 8161@section Pragma Unsuppress 8162 8163 8164Syntax: 8165 8166@example 8167pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8168@end example 8169 8170This pragma undoes the effect of a previous pragma @cite{Suppress}. If 8171there is no corresponding pragma @cite{Suppress} in effect, it has no 8172effect. The range of the effect is the same as for pragma 8173@cite{Suppress}. The meaning of the arguments is identical to that used 8174in pragma @cite{Suppress}. 8175 8176One important application is to ensure that checks are on in cases where 8177code depends on the checks for its correct functioning, so that the code 8178will compile correctly even if the compiler switches are set to suppress 8179checks. For example, in a program that depends on external names of tagged 8180types and wants to ensure that the duplicated tag check occurs even if all 8181run-time checks are suppressed by a compiler switch, the following 8182configuration pragma will ensure this test is not suppressed: 8183 8184@example 8185pragma Unsuppress (Duplicated_Tag_Check); 8186@end example 8187 8188This pragma is standard in Ada 2005. It is available in all earlier versions 8189of Ada as an implementation-defined pragma. 8190 8191Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8192number of implementation-defined check names. See the description of pragma 8193@cite{Suppress} for full details. 8194 8195@node Pragma Use_VADS_Size,Pragma Validity_Checks,Pragma Unsuppress,Implementation Defined Pragmas 8196@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{db} 8197@section Pragma Use_VADS_Size 8198 8199 8200@geindex Size 8201@geindex VADS compatibility 8202 8203@geindex Rational profile 8204 8205Syntax: 8206 8207@example 8208pragma Use_VADS_Size; 8209@end example 8210 8211This is a configuration pragma. In a unit to which it applies, any use 8212of the 'Size attribute is automatically interpreted as a use of the 8213'VADS_Size attribute. Note that this may result in incorrect semantic 8214processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8215the handling of existing code which depends on the interpretation of Size 8216as implemented in the VADS compiler. See description of the VADS_Size 8217attribute for further details. 8218 8219@node Pragma Validity_Checks,Pragma Volatile,Pragma Use_VADS_Size,Implementation Defined Pragmas 8220@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{dc} 8221@section Pragma Validity_Checks 8222 8223 8224Syntax: 8225 8226@example 8227pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8228@end example 8229 8230This pragma is used in conjunction with compiler switches to control the 8231built-in validity checking provided by GNAT. The compiler switches, if set 8232provide an initial setting for the switches, and this pragma may be used 8233to modify these settings, or the settings may be provided entirely by 8234the use of the pragma. This pragma can be used anywhere that a pragma 8235is legal, including use as a configuration pragma (including use in 8236the @code{gnat.adc} file). 8237 8238The form with a string literal specifies which validity options are to be 8239activated. The validity checks are first set to include only the default 8240reference manual settings, and then a string of letters in the string 8241specifies the exact set of options required. The form of this string 8242is exactly as described for the @emph{-gnatVx} compiler switch (see the 8243GNAT User's Guide for details). For example the following two 8244methods can be used to enable validity checking for mode @cite{in} and 8245@cite{in out} subprogram parameters: 8246 8247 8248@itemize * 8249 8250@item 8251@example 8252pragma Validity_Checks ("im"); 8253@end example 8254 8255@item 8256@example 8257$ gcc -c -gnatVim ... 8258@end example 8259@end itemize 8260 8261The form ALL_CHECKS activates all standard checks (its use is equivalent 8262to the use of the @cite{gnatva} switch. 8263 8264The forms with @cite{Off} and @cite{On} 8265can be used to temporarily disable validity checks 8266as shown in the following example: 8267 8268@example 8269pragma Validity_Checks ("c"); -- validity checks for copies 8270pragma Validity_Checks (Off); -- turn off validity checks 8271A := B; -- B will not be validity checked 8272pragma Validity_Checks (On); -- turn validity checks back on 8273A := C; -- C will be validity checked 8274@end example 8275 8276@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8277@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{dd} 8278@section Pragma Volatile 8279 8280 8281Syntax: 8282 8283@example 8284pragma Volatile (LOCAL_NAME); 8285@end example 8286 8287This pragma is defined by the Ada Reference Manual, and the GNAT 8288implementation is fully conformant with this definition. The reason it 8289is mentioned in this section is that a pragma of the same name was supplied 8290in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8291implementation of pragma Volatile is upwards compatible with the 8292implementation in DEC Ada 83. 8293 8294@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8295@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{de} 8296@section Pragma Volatile_Full_Access 8297 8298 8299Syntax: 8300 8301@example 8302pragma Volatile_Full_Access (LOCAL_NAME); 8303@end example 8304 8305This is similar in effect to pragma Volatile, except that any reference to the 8306object is guaranteed to be done only with instructions that read or write all 8307the bits of the object. Furthermore, if the object is of a composite type, 8308then any reference to a component of the object is guaranteed to read and/or 8309write all the bits of the object. 8310 8311The intention is that this be suitable for use with memory-mapped I/O devices 8312on some machines. Note that there are two important respects in which this is 8313different from @cite{pragma Atomic}. First a reference to a @cite{Volatile_Full_Access} 8314object is not a sequential action in the RM 9.10 sense and, therefore, does 8315not create a synchronization point. Second, in the case of @cite{pragma Atomic}, 8316there is no guarantee that all the bits will be accessed if the reference 8317is not to the whole object; the compiler is allowed (and generally will) 8318access only part of the object in this case. 8319 8320It is not permissible to specify @cite{Atomic} and @cite{Volatile_Full_Access} for 8321the same object. 8322 8323It is not permissible to specify @cite{Volatile_Full_Access} for a composite 8324(record or array) type or object that has at least one @cite{Aliased} component. 8325 8326@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8327@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{df} 8328@section Pragma Volatile_Function 8329 8330 8331Syntax: 8332 8333@example 8334pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8335@end example 8336 8337For the semantics of this pragma, see the entry for aspect @cite{Volatile_Function} 8338in the SPARK 2014 Reference Manual, section 7.1.2. 8339 8340@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8341@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{e0} 8342@section Pragma Warning_As_Error 8343 8344 8345Syntax: 8346 8347@example 8348pragma Warning_As_Error (static_string_EXPRESSION); 8349@end example 8350 8351This configuration pragma allows the programmer to specify a set 8352of warnings that will be treated as errors. Any warning which 8353matches the pattern given by the pragma argument will be treated 8354as an error. This gives much more precise control that -gnatwe 8355which treats all warnings as errors. 8356 8357The pattern may contain asterisks, which match zero or more characters in 8358the message. For example, you can use 8359@cite{pragma Warning_As_Error ("bits of*unused")} to treat the warning 8360message @cite{warning: 960 bits of "a" unused} as an error. No other regular 8361expression notations are permitted. All characters other than asterisk in 8362these three specific cases are treated as literal characters in the match. 8363The match is case insensitive, for example XYZ matches xyz. 8364 8365Note that the pattern matches if it occurs anywhere within the warning 8366message string (it is not necessary to put an asterisk at the start and 8367the end of the message, since this is implied). 8368 8369Another possibility for the static_string_EXPRESSION which works whether 8370or not error tags are enabled (@emph{-gnatw.d}) is to use the 8371@emph{-gnatw} tag string, enclosed in brackets, 8372as shown in the example below, to treat a class of warnings as errors. 8373 8374The above use of patterns to match the message applies only to warning 8375messages generated by the front end. This pragma can also be applied to 8376warnings provided by the back end and mentioned in @ref{e1,,Pragma Warnings}. 8377By using a single full @emph{-Wxxx} switch in the pragma, such warnings 8378can also be treated as errors. 8379 8380The pragma can appear either in a global configuration pragma file 8381(e.g. @code{gnat.adc}), or at the start of a file. Given a global 8382configuration pragma file containing: 8383 8384@example 8385pragma Warning_As_Error ("[-gnatwj]"); 8386@end example 8387 8388which will treat all obsolescent feature warnings as errors, the 8389following program compiles as shown (compile options here are 8390@emph{-gnatwa.d -gnatl -gnatj55}). 8391 8392@example 8393 1. pragma Warning_As_Error ("*never assigned*"); 8394 2. function Warnerr return String is 8395 3. X : Integer; 8396 | 8397 >>> error: variable "X" is never read and 8398 never assigned [-gnatwv] [warning-as-error] 8399 8400 4. Y : Integer; 8401 | 8402 >>> warning: variable "Y" is assigned but 8403 never read [-gnatwu] 8404 8405 5. begin 8406 6. Y := 0; 8407 7. return %ABC%; 8408 | 8409 >>> error: use of "%" is an obsolescent 8410 feature (RM J.2(4)), use """ instead 8411 [-gnatwj] [warning-as-error] 8412 8413 8. end; 8414 84158 lines: No errors, 3 warnings (2 treated as errors) 8416@end example 8417 8418Note that this pragma does not affect the set of warnings issued in 8419any way, it merely changes the effect of a matching warning if one 8420is produced as a result of other warnings options. As shown in this 8421example, if the pragma results in a warning being treated as an error, 8422the tag is changed from "warning:" to "error:" and the string 8423"[warning-as-error]" is appended to the end of the message. 8424 8425@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 8426@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{e2}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{e1} 8427@section Pragma Warnings 8428 8429 8430Syntax: 8431 8432@example 8433pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 8434 8435DETAILS ::= On | Off 8436DETAILS ::= On | Off, local_NAME 8437DETAILS ::= static_string_EXPRESSION 8438DETAILS ::= On | Off, static_string_EXPRESSION 8439 8440TOOL_NAME ::= GNAT | GNATProve 8441 8442REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 8443@end example 8444 8445Note: in Ada 83 mode, a string literal may be used in place of a static string 8446expression (which does not exist in Ada 83). 8447 8448Note if the second argument of @cite{DETAILS} is a @cite{local_NAME} then the 8449second form is always understood. If the intention is to use 8450the fourth form, then you can write @cite{NAME & ""} to force the 8451intepretation as a @cite{static_string_EXPRESSION}. 8452 8453Note: if the first argument is a valid @cite{TOOL_NAME}, it will be interpreted 8454that way. The use of the @cite{TOOL_NAME} argument is relevant only to users 8455of SPARK and GNATprove, see last part of this section for details. 8456 8457Normally warnings are enabled, with the output being controlled by 8458the command line switch. Warnings (@cite{Off}) turns off generation of 8459warnings until a Warnings (@cite{On}) is encountered or the end of the 8460current unit. If generation of warnings is turned off using this 8461pragma, then some or all of the warning messages are suppressed, 8462regardless of the setting of the command line switches. 8463 8464The @cite{Reason} parameter may optionally appear as the last argument 8465in any of the forms of this pragma. It is intended purely for the 8466purposes of documenting the reason for the @cite{Warnings} pragma. 8467The compiler will check that the argument is a static string but 8468otherwise ignore this argument. Other tools may provide specialized 8469processing for this string. 8470 8471The form with a single argument (or two arguments if Reason present), 8472where the first argument is @cite{ON} or @cite{OFF} 8473may be used as a configuration pragma. 8474 8475If the @cite{LOCAL_NAME} parameter is present, warnings are suppressed for 8476the specified entity. This suppression is effective from the point where 8477it occurs till the end of the extended scope of the variable (similar to 8478the scope of @cite{Suppress}). This form cannot be used as a configuration 8479pragma. 8480 8481In the case where the first argument is other than @cite{ON} or 8482@cite{OFF}, 8483the third form with a single static_string_EXPRESSION argument (and possible 8484reason) provides more precise 8485control over which warnings are active. The string is a list of letters 8486specifying which warnings are to be activated and which deactivated. The 8487code for these letters is the same as the string used in the command 8488line switch controlling warnings. For a brief summary, use the gnatmake 8489command with no arguments, which will generate usage information containing 8490the list of warnings switches supported. For 8491full details see the section on @cite{Warning Message Control} in the 8492@cite{GNAT User's Guide}. 8493This form can also be used as a configuration pragma. 8494 8495The warnings controlled by the @emph{-gnatw} switch are generated by the 8496front end of the compiler. The GCC back end can provide additional warnings 8497and they are controlled by the @emph{-W} switch. Such warnings can be 8498identified by the appearance of a string of the form @cite{[-Wxxx]} in the 8499message which designates the @emph{-Wxxx} switch that controls the message. 8500The form with a single static_string_EXPRESSION argument also works for these 8501warnings, but the string must be a single full @emph{-Wxxx} switch in this 8502case. The above reference lists a few examples of these additional warnings. 8503 8504The specified warnings will be in effect until the end of the program 8505or another pragma Warnings is encountered. The effect of the pragma is 8506cumulative. Initially the set of warnings is the standard default set 8507as possibly modified by compiler switches. Then each pragma Warning 8508modifies this set of warnings as specified. This form of the pragma may 8509also be used as a configuration pragma. 8510 8511The fourth form, with an @cite{On|Off} parameter and a string, is used to 8512control individual messages, based on their text. The string argument 8513is a pattern that is used to match against the text of individual 8514warning messages (not including the initial "warning: " tag). 8515 8516The pattern may contain asterisks, which match zero or more characters in 8517the message. For example, you can use 8518@cite{pragma Warnings (Off@comma{} "bits of*unused")} to suppress the warning 8519message @cite{warning: 960 bits of "a" unused}. No other regular 8520expression notations are permitted. All characters other than asterisk in 8521these three specific cases are treated as literal characters in the match. 8522The match is case insensitive, for example XYZ matches xyz. 8523 8524Note that the pattern matches if it occurs anywhere within the warning 8525message string (it is not necessary to put an asterisk at the start and 8526the end of the message, since this is implied). 8527 8528The above use of patterns to match the message applies only to warning 8529messages generated by the front end. This form of the pragma with a string 8530argument can also be used to control warnings provided by the back end and 8531mentioned above. By using a single full @emph{-Wxxx} switch in the pragma, 8532such warnings can be turned on and off. 8533 8534There are two ways to use the pragma in this form. The OFF form can be used 8535as a configuration pragma. The effect is to suppress all warnings (if any) 8536that match the pattern string throughout the compilation (or match the 8537-W switch in the back end case). 8538 8539The second usage is to suppress a warning locally, and in this case, two 8540pragmas must appear in sequence: 8541 8542@example 8543pragma Warnings (Off, Pattern); 8544... code where given warning is to be suppressed 8545pragma Warnings (On, Pattern); 8546@end example 8547 8548In this usage, the pattern string must match in the Off and On 8549pragmas, and (if @emph{-gnatw.w} is given) at least one matching 8550warning must be suppressed. 8551 8552Note: to write a string that will match any warning, use the string 8553@cite{"***"}. It will not work to use a single asterisk or two 8554asterisks since this looks like an operator name. This form with three 8555asterisks is similar in effect to specifying @cite{pragma Warnings (Off)} except (if @emph{-gnatw.w} is given) that a matching 8556@cite{pragma Warnings (On@comma{} "***")} will be required. This can be 8557helpful in avoiding forgetting to turn warnings back on. 8558 8559Note: the debug flag -gnatd.i (@cite{/NOWARNINGS_PRAGMAS} in VMS) can be 8560used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 8561be useful in checking whether obsolete pragmas in existing programs are hiding 8562real problems. 8563 8564Note: pragma Warnings does not affect the processing of style messages. See 8565separate entry for pragma Style_Checks for control of style messages. 8566 8567Users of the formal verification tool GNATprove for the SPARK subset of Ada may 8568use the version of the pragma with a @cite{TOOL_NAME} parameter. 8569 8570If present, @cite{TOOL_NAME} is the name of a tool, currently either @cite{GNAT} for the 8571compiler or @cite{GNATprove} for the formal verification tool. A given tool only 8572takes into account pragma Warnings that do not specify a tool name, or that 8573specify the matching tool name. This makes it possible to disable warnings 8574selectively for each tool, and as a consequence to detect useless pragma 8575Warnings with switch @cite{-gnatw.w}. 8576 8577@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 8578@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{e3} 8579@section Pragma Weak_External 8580 8581 8582Syntax: 8583 8584@example 8585pragma Weak_External ([Entity =>] LOCAL_NAME); 8586@end example 8587 8588@cite{LOCAL_NAME} must refer to an object that is declared at the library 8589level. This pragma specifies that the given entity should be marked as a 8590weak symbol for the linker. It is equivalent to @cite{__attribute__((weak))} 8591in GNU C and causes @cite{LOCAL_NAME} to be emitted as a weak symbol instead 8592of a regular symbol, that is to say a symbol that does not have to be 8593resolved by the linker if used in conjunction with a pragma Import. 8594 8595When a weak symbol is not resolved by the linker, its address is set to 8596zero. This is useful in writing interfaces to external modules that may 8597or may not be linked in the final executable, for example depending on 8598configuration settings. 8599 8600If a program references at run time an entity to which this pragma has been 8601applied, and the corresponding symbol was not resolved at link time, then 8602the execution of the program is erroneous. It is not erroneous to take the 8603Address of such an entity, for example to guard potential references, 8604as shown in the example below. 8605 8606Some file formats do not support weak symbols so not all target machines 8607support this pragma. 8608 8609@example 8610-- Example of the use of pragma Weak_External 8611 8612package External_Module is 8613 key : Integer; 8614 pragma Import (C, key); 8615 pragma Weak_External (key); 8616 function Present return boolean; 8617end External_Module; 8618 8619with System; use System; 8620package body External_Module is 8621 function Present return boolean is 8622 begin 8623 return key'Address /= System.Null_Address; 8624 end Present; 8625end External_Module; 8626@end example 8627 8628@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 8629@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{e4} 8630@section Pragma Wide_Character_Encoding 8631 8632 8633Syntax: 8634 8635@example 8636pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 8637@end example 8638 8639This pragma specifies the wide character encoding to be used in program 8640source text appearing subsequently. It is a configuration pragma, but may 8641also be used at any point that a pragma is allowed, and it is permissible 8642to have more than one such pragma in a file, allowing multiple encodings 8643to appear within the same file. 8644 8645The argument can be an identifier or a character literal. In the identifier 8646case, it is one of @cite{HEX}, @cite{UPPER}, @cite{SHIFT_JIS}, 8647@cite{EUC}, @cite{UTF8}, or @cite{BRACKETS}. In the character literal 8648case it is correspondingly one of the characters @code{h}, @code{u}, 8649@code{s}, @code{e}, @code{8}, or @code{b}. 8650 8651Note that when the pragma is used within a file, it affects only the 8652encoding within that file, and does not affect withed units, specs, 8653or subunits. 8654 8655@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 8656@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{e5}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{e6}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{e7} 8657@chapter Implementation Defined Aspects 8658 8659 8660Ada defines (throughout the Ada 2012 reference manual, summarized 8661in Annex K) a set of aspects that can be specified for certain entities. 8662These language defined aspects are implemented in GNAT in Ada 2012 mode 8663and work as described in the Ada 2012 Reference Manual. 8664 8665In addition, Ada 2012 allows implementations to define additional aspects 8666whose meaning is defined by the implementation. GNAT provides 8667a number of these implementation-defined aspects which can be used 8668to extend and enhance the functionality of the compiler. This section of 8669the GNAT reference manual describes these additional aspects. 8670 8671Note that any program using these aspects may not be portable to 8672other compilers (although GNAT implements this set of aspects on all 8673platforms). Therefore if portability to other compilers is an important 8674consideration, you should minimize the use of these aspects. 8675 8676Note that for many of these aspects, the effect is essentially similar 8677to the use of a pragma or attribute specification with the same name 8678applied to the entity. For example, if we write: 8679 8680@example 8681type R is range 1 .. 100 8682 with Value_Size => 10; 8683@end example 8684 8685then the effect is the same as: 8686 8687@example 8688type R is range 1 .. 100; 8689for R'Value_Size use 10; 8690@end example 8691 8692and if we write: 8693 8694@example 8695type R is new Integer 8696 with Shared => True; 8697@end example 8698 8699then the effect is the same as: 8700 8701@example 8702type R is new Integer; 8703pragma Shared (R); 8704@end example 8705 8706In the documentation below, such cases are simply marked 8707as being boolean aspects equivalent to the corresponding pragma 8708or attribute definition clause. 8709 8710@menu 8711* Aspect Abstract_State:: 8712* Annotate:: 8713* Aspect Async_Readers:: 8714* Aspect Async_Writers:: 8715* Aspect Constant_After_Elaboration:: 8716* Aspect Contract_Cases:: 8717* Aspect Depends:: 8718* Aspect Default_Initial_Condition:: 8719* Aspect Dimension:: 8720* Aspect Dimension_System:: 8721* Aspect Disable_Controlled:: 8722* Aspect Effective_Reads:: 8723* Aspect Effective_Writes:: 8724* Aspect Extensions_Visible:: 8725* Aspect Favor_Top_Level:: 8726* Aspect Ghost:: 8727* Aspect Global:: 8728* Aspect Initial_Condition:: 8729* Aspect Initializes:: 8730* Aspect Inline_Always:: 8731* Aspect Invariant:: 8732* Aspect Invariant'Class:: 8733* Aspect Iterable:: 8734* Aspect Linker_Section:: 8735* Aspect Lock_Free:: 8736* Aspect No_Elaboration_Code_All:: 8737* Aspect No_Tagged_Streams:: 8738* Aspect Object_Size:: 8739* Aspect Obsolescent:: 8740* Aspect Part_Of:: 8741* Aspect Persistent_BSS:: 8742* Aspect Predicate:: 8743* Aspect Pure_Function:: 8744* Aspect Refined_Depends:: 8745* Aspect Refined_Global:: 8746* Aspect Refined_Post:: 8747* Aspect Refined_State:: 8748* Aspect Remote_Access_Type:: 8749* Aspect Scalar_Storage_Order:: 8750* Aspect Shared:: 8751* Aspect Simple_Storage_Pool:: 8752* Aspect Simple_Storage_Pool_Type:: 8753* Aspect SPARK_Mode:: 8754* Aspect Suppress_Debug_Info:: 8755* Aspect Suppress_Initialization:: 8756* Aspect Test_Case:: 8757* Aspect Thread_Local_Storage:: 8758* Aspect Universal_Aliasing:: 8759* Aspect Universal_Data:: 8760* Aspect Unmodified:: 8761* Aspect Unreferenced:: 8762* Aspect Unreferenced_Objects:: 8763* Aspect Value_Size:: 8764* Aspect Volatile_Full_Access:: 8765* Aspect Volatile_Function:: 8766* Aspect Warnings:: 8767 8768@end menu 8769 8770@node Aspect Abstract_State,Annotate,,Implementation Defined Aspects 8771@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{e8} 8772@section Aspect Abstract_State 8773 8774 8775@geindex Abstract_State 8776 8777This aspect is equivalent to pragma @cite{Abstract_State}. 8778 8779@node Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 8780@anchor{gnat_rm/implementation_defined_aspects annotate}@anchor{e9} 8781@section Annotate 8782 8783 8784@geindex Annotate 8785 8786There are three forms of this aspect (where ID is an identifier, 8787and ARG is a general expression). 8788 8789 8790@table @asis 8791 8792@item @emph{Annotate => ID} 8793 8794Equivalent to @cite{pragma Annotate (ID@comma{} Entity => Name);} 8795 8796@item @emph{Annotate => (ID)} 8797 8798Equivalent to @cite{pragma Annotate (ID@comma{} Entity => Name);} 8799 8800@item @emph{Annotate => (ID ,ID @{, ARG@})} 8801 8802Equivalent to @cite{pragma Annotate (ID@comma{} ID @{@comma{} ARG@}@comma{} Entity => Name);} 8803@end table 8804 8805@node Aspect Async_Readers,Aspect Async_Writers,Annotate,Implementation Defined Aspects 8806@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{ea} 8807@section Aspect Async_Readers 8808 8809 8810@geindex Async_Readers 8811 8812This boolean aspect is equivalent to pragma @cite{Async_Readers}. 8813 8814@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 8815@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{eb} 8816@section Aspect Async_Writers 8817 8818 8819@geindex Async_Writers 8820 8821This boolean aspect is equivalent to pragma @cite{Async_Writers}. 8822 8823@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 8824@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{ec} 8825@section Aspect Constant_After_Elaboration 8826 8827 8828@geindex Constant_After_Elaboration 8829 8830This aspect is equivalent to pragma @cite{Constant_After_Elaboration}. 8831 8832@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 8833@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{ed} 8834@section Aspect Contract_Cases 8835 8836 8837@geindex Contract_Cases 8838 8839This aspect is equivalent to pragma @cite{Contract_Cases}, the sequence 8840of clauses being enclosed in parentheses so that syntactically it is an 8841aggregate. 8842 8843@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 8844@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{ee} 8845@section Aspect Depends 8846 8847 8848@geindex Depends 8849 8850This aspect is equivalent to pragma @cite{Depends}. 8851 8852@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 8853@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{ef} 8854@section Aspect Default_Initial_Condition 8855 8856 8857@geindex Default_Initial_Condition 8858 8859This aspect is equivalent to pragma @cite{Default_Initial_Condition}. 8860 8861@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 8862@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{f0} 8863@section Aspect Dimension 8864 8865 8866@geindex Dimension 8867 8868The @cite{Dimension} aspect is used to specify the dimensions of a given 8869subtype of a dimensioned numeric type. The aspect also specifies a symbol 8870used when doing formatted output of dimensioned quantities. The syntax is: 8871 8872@example 8873with Dimension => 8874 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 8875 8876SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 8877 8878DIMENSION_VALUE ::= 8879 RATIONAL 8880| others => RATIONAL 8881| DISCRETE_CHOICE_LIST => RATIONAL 8882 8883RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 8884@end example 8885 8886This aspect can only be applied to a subtype whose parent type has 8887a @cite{Dimension_Systen} aspect. The aspect must specify values for 8888all dimensions of the system. The rational values are the powers of the 8889corresponding dimensions that are used by the compiler to verify that 8890physical (numeric) computations are dimensionally consistent. For example, 8891the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 8892For further examples of the usage 8893of this aspect, see package @cite{System.Dim.Mks}. 8894Note that when the dimensioned type is an integer type, then any 8895dimension value must be an integer literal. 8896 8897@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 8898@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{f1} 8899@section Aspect Dimension_System 8900 8901 8902@geindex Dimension_System 8903 8904The @cite{Dimension_System} aspect is used to define a system of 8905dimensions that will be used in subsequent subtype declarations with 8906@cite{Dimension} aspects that reference this system. The syntax is: 8907 8908@example 8909with Dimension_System => (DIMENSION @{, DIMENSION@}); 8910 8911DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 8912 [Unit_Symbol =>] SYMBOL, 8913 [Dim_Symbol =>] SYMBOL) 8914 8915SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 8916@end example 8917 8918This aspect is applied to a type, which must be a numeric derived type 8919(typically a floating-point type), that 8920will represent values within the dimension system. Each @cite{DIMENSION} 8921corresponds to one particular dimension. A maximum of 7 dimensions may 8922be specified. @cite{Unit_Name} is the name of the dimension (for example 8923@cite{Meter}). @cite{Unit_Symbol} is the shorthand used for quantities 8924of this dimension (for example @cite{m} for @cite{Meter}). 8925@cite{Dim_Symbol} gives 8926the identification within the dimension system (typically this is a 8927single letter, e.g. @cite{L} standing for length for unit name @cite{Meter}). 8928The @cite{Unit_Symbol} is used in formatted output of dimensioned quantities. 8929The @cite{Dim_Symbol} is used in error messages when numeric operations have 8930inconsistent dimensions. 8931 8932GNAT provides the standard definition of the International MKS system in 8933the run-time package @cite{System.Dim.Mks}. You can easily define 8934similar packages for cgs units or British units, and define conversion factors 8935between values in different systems. The MKS system is characterized by the 8936following aspect: 8937 8938@example 8939type Mks_Type is new Long_Long_Float with 8940 Dimension_System => ( 8941 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 8942 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 8943 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 8944 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 8945 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 8946 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 8947 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 8948@end example 8949 8950Note that in the above type definition, we use the @cite{at} symbol (@code{@@}) to 8951represent a theta character (avoiding the use of extended Latin-1 8952characters in this context). 8953 8954See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users 8955Guide for detailed examples of use of the dimension system. 8956 8957@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 8958@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{f2} 8959@section Aspect Disable_Controlled 8960 8961 8962@geindex Disable_Controlled 8963 8964The aspect @cite{Disable_Controlled} is defined for controlled record types. If 8965active, this aspect causes suppression of all related calls to @cite{Initialize}, 8966@cite{Adjust}, and @cite{Finalize}. The intended use is for conditional compilation, 8967where for example you might want a record to be controlled or not depending on 8968whether some run-time check is enabled or suppressed. 8969 8970@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 8971@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{f3} 8972@section Aspect Effective_Reads 8973 8974 8975@geindex Effective_Reads 8976 8977This aspect is equivalent to pragma @cite{Effective_Reads}. 8978 8979@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 8980@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{f4} 8981@section Aspect Effective_Writes 8982 8983 8984@geindex Effective_Writes 8985 8986This aspect is equivalent to pragma @cite{Effective_Writes}. 8987 8988@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 8989@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{f5} 8990@section Aspect Extensions_Visible 8991 8992 8993@geindex Extensions_Visible 8994 8995This aspect is equivalent to pragma @cite{Extensions_Visible}. 8996 8997@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 8998@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{f6} 8999@section Aspect Favor_Top_Level 9000 9001 9002@geindex Favor_Top_Level 9003 9004This boolean aspect is equivalent to pragma @cite{Favor_Top_Level}. 9005 9006@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9007@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{f7} 9008@section Aspect Ghost 9009 9010 9011@geindex Ghost 9012 9013This aspect is equivalent to pragma @cite{Ghost}. 9014 9015@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9016@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{f8} 9017@section Aspect Global 9018 9019 9020@geindex Global 9021 9022This aspect is equivalent to pragma @cite{Global}. 9023 9024@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9025@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{f9} 9026@section Aspect Initial_Condition 9027 9028 9029@geindex Initial_Condition 9030 9031This aspect is equivalent to pragma @cite{Initial_Condition}. 9032 9033@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9034@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{fa} 9035@section Aspect Initializes 9036 9037 9038@geindex Initializes 9039 9040This aspect is equivalent to pragma @cite{Initializes}. 9041 9042@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9043@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{fb} 9044@section Aspect Inline_Always 9045 9046 9047@geindex Inline_Always 9048 9049This boolean aspect is equivalent to pragma @cite{Inline_Always}. 9050 9051@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects 9052@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{fc} 9053@section Aspect Invariant 9054 9055 9056@geindex Invariant 9057 9058This aspect is equivalent to pragma @cite{Invariant}. It is a 9059synonym for the language defined aspect @cite{Type_Invariant} except 9060that it is separately controllable using pragma @cite{Assertion_Policy}. 9061 9062@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9063@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{fd} 9064@section Aspect Invariant'Class 9065 9066 9067@geindex Invariant'Class 9068 9069This aspect is equivalent to pragma @cite{Type_Invariant_Class}. It is a 9070synonym for the language defined aspect @cite{Type_Invariant'Class} except 9071that it is separately controllable using pragma @cite{Assertion_Policy}. 9072 9073@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects 9074@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{fe} 9075@section Aspect Iterable 9076 9077 9078@geindex Iterable 9079 9080This aspect provides a light-weight mechanism for loops and quantified 9081expressions over container types, without the overhead imposed by the tampering 9082checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9083with four named components: @cite{First}, @cite{Next}, @cite{Has_Element}, and @cite{Element} (the 9084last one being optional). When only 3 components are specified, only the 9085@cite{for .. in} form of iteration over cursors is available. When all 4 components 9086are specified, both this form and the @cite{for .. of} form of iteration over 9087elements are available. The following is a typical example of use: 9088 9089@example 9090type List is private with 9091 Iterable => (First => First_Cursor, 9092 Next => Advance, 9093 Has_Element => Cursor_Has_Element, 9094 [Element => Get_Element]); 9095@end example 9096 9097 9098@itemize * 9099 9100@item 9101The value denoted by @cite{First} must denote a primitive operation of the 9102container type that returns a @cite{Cursor}, which must a be a type declared in 9103the container package or visible from it. For example: 9104@end itemize 9105 9106@example 9107function First_Cursor (Cont : Container) return Cursor; 9108@end example 9109 9110 9111@itemize * 9112 9113@item 9114The value of @cite{Next} is a primitive operation of the container type that takes 9115both a container and a cursor and yields a cursor. For example: 9116@end itemize 9117 9118@example 9119function Advance (Cont : Container; Position : Cursor) return Cursor; 9120@end example 9121 9122 9123@itemize * 9124 9125@item 9126The value of @cite{Has_Element} is a primitive operation of the container type 9127that takes both a container and a cursor and yields a boolean. For example: 9128@end itemize 9129 9130@example 9131function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9132@end example 9133 9134 9135@itemize * 9136 9137@item 9138The value of @cite{Element} is a primitive operation of the container type that 9139takes both a container and a cursor and yields an @cite{Element_Type}, which must 9140be a type declared in the container package or visible from it. For example: 9141@end itemize 9142 9143@example 9144function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9145@end example 9146 9147This aspect is used in the GNAT-defined formal container packages. 9148 9149@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9150@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{ff} 9151@section Aspect Linker_Section 9152 9153 9154@geindex Linker_Section 9155 9156This aspect is equivalent to an @cite{Linker_Section} pragma. 9157 9158@node Aspect Lock_Free,Aspect No_Elaboration_Code_All,Aspect Linker_Section,Implementation Defined Aspects 9159@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{100} 9160@section Aspect Lock_Free 9161 9162 9163@geindex Lock_Free 9164 9165This boolean aspect is equivalent to pragma @cite{Lock_Free}. 9166 9167@node Aspect No_Elaboration_Code_All,Aspect No_Tagged_Streams,Aspect Lock_Free,Implementation Defined Aspects 9168@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{101} 9169@section Aspect No_Elaboration_Code_All 9170 9171 9172@geindex No_Elaboration_Code_All 9173 9174This aspect is equivalent to a @cite{pragma No_Elaboration_Code_All} 9175statement for a program unit. 9176 9177@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9178@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{102} 9179@section Aspect No_Tagged_Streams 9180 9181 9182@geindex No_Tagged_Streams 9183 9184This aspect is equivalent to a @cite{pragma No_Tagged_Streams} with an 9185argument specifying a root tagged type (thus this aspect can only be 9186applied to such a type). 9187 9188@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects 9189@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{103} 9190@section Aspect Object_Size 9191 9192 9193@geindex Object_Size 9194 9195This aspect is equivalent to an @cite{Object_Size} attribute definition 9196clause. 9197 9198@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9199@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{104} 9200@section Aspect Obsolescent 9201 9202 9203@geindex Obsolsecent 9204 9205This aspect is equivalent to an @cite{Obsolescent} pragma. Note that the 9206evaluation of this aspect happens at the point of occurrence, it is not 9207delayed until the freeze point. 9208 9209@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9210@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{105} 9211@section Aspect Part_Of 9212 9213 9214@geindex Part_Of 9215 9216This aspect is equivalent to pragma @cite{Part_Of}. 9217 9218@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9219@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{106} 9220@section Aspect Persistent_BSS 9221 9222 9223@geindex Persistent_BSS 9224 9225This boolean aspect is equivalent to pragma @cite{Persistent_BSS}. 9226 9227@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9228@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{107} 9229@section Aspect Predicate 9230 9231 9232@geindex Predicate 9233 9234This aspect is equivalent to pragma @cite{Predicate}. It is thus 9235similar to the language defined aspects @cite{Dynamic_Predicate} 9236and @cite{Static_Predicate} except that whether the resulting 9237predicate is static or dynamic is controlled by the form of the 9238expression. It is also separately controllable using pragma 9239@cite{Assertion_Policy}. 9240 9241@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9242@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{108} 9243@section Aspect Pure_Function 9244 9245 9246@geindex Pure_Function 9247 9248This boolean aspect is equivalent to pragma @cite{Pure_Function}. 9249 9250@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9251@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{109} 9252@section Aspect Refined_Depends 9253 9254 9255@geindex Refined_Depends 9256 9257This aspect is equivalent to pragma @cite{Refined_Depends}. 9258 9259@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9260@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{10a} 9261@section Aspect Refined_Global 9262 9263 9264@geindex Refined_Global 9265 9266This aspect is equivalent to pragma @cite{Refined_Global}. 9267 9268@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9269@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{10b} 9270@section Aspect Refined_Post 9271 9272 9273@geindex Refined_Post 9274 9275This aspect is equivalent to pragma @cite{Refined_Post}. 9276 9277@node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects 9278@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{10c} 9279@section Aspect Refined_State 9280 9281 9282@geindex Refined_State 9283 9284This aspect is equivalent to pragma @cite{Refined_State}. 9285 9286@node Aspect Remote_Access_Type,Aspect Scalar_Storage_Order,Aspect Refined_State,Implementation Defined Aspects 9287@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{10d} 9288@section Aspect Remote_Access_Type 9289 9290 9291@geindex Remote_Access_Type 9292 9293This aspect is equivalent to pragma @cite{Remote_Access_Type}. 9294 9295@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Remote_Access_Type,Implementation Defined Aspects 9296@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{10e} 9297@section Aspect Scalar_Storage_Order 9298 9299 9300@geindex Scalar_Storage_Order 9301 9302This aspect is equivalent to a @cite{Scalar_Storage_Order} 9303attribute definition clause. 9304 9305@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 9306@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{10f} 9307@section Aspect Shared 9308 9309 9310@geindex Shared 9311 9312This boolean aspect is equivalent to pragma @cite{Shared}, 9313and is thus a synonym for aspect @cite{Atomic}. 9314 9315@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 9316@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{110} 9317@section Aspect Simple_Storage_Pool 9318 9319 9320@geindex Simple_Storage_Pool 9321 9322This aspect is equivalent to a @cite{Simple_Storage_Pool} 9323attribute definition clause. 9324 9325@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 9326@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{111} 9327@section Aspect Simple_Storage_Pool_Type 9328 9329 9330@geindex Simple_Storage_Pool_Type 9331 9332This boolean aspect is equivalent to pragma @cite{Simple_Storage_Pool_Type}. 9333 9334@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 9335@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{112} 9336@section Aspect SPARK_Mode 9337 9338 9339@geindex SPARK_Mode 9340 9341This aspect is equivalent to pragma @cite{SPARK_Mode} and 9342may be specified for either or both of the specification and body 9343of a subprogram or package. 9344 9345@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 9346@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{113} 9347@section Aspect Suppress_Debug_Info 9348 9349 9350@geindex Suppress_Debug_Info 9351 9352This boolean aspect is equivalent to pragma @cite{Suppress_Debug_Info}. 9353 9354@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 9355@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{114} 9356@section Aspect Suppress_Initialization 9357 9358 9359@geindex Suppress_Initialization 9360 9361This boolean aspect is equivalent to pragma @cite{Suppress_Initialization}. 9362 9363@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 9364@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{115} 9365@section Aspect Test_Case 9366 9367 9368@geindex Test_Case 9369 9370This aspect is equivalent to pragma @cite{Test_Case}. 9371 9372@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 9373@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{116} 9374@section Aspect Thread_Local_Storage 9375 9376 9377@geindex Thread_Local_Storage 9378 9379This boolean aspect is equivalent to pragma @cite{Thread_Local_Storage}. 9380 9381@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects 9382@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{117} 9383@section Aspect Universal_Aliasing 9384 9385 9386@geindex Universal_Aliasing 9387 9388This boolean aspect is equivalent to pragma @cite{Universal_Aliasing}. 9389 9390@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects 9391@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{118} 9392@section Aspect Universal_Data 9393 9394 9395@geindex Universal_Data 9396 9397This aspect is equivalent to pragma @cite{Universal_Data}. 9398 9399@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects 9400@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{119} 9401@section Aspect Unmodified 9402 9403 9404@geindex Unmodified 9405 9406This boolean aspect is equivalent to pragma @cite{Unmodified}. 9407 9408@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 9409@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{11a} 9410@section Aspect Unreferenced 9411 9412 9413@geindex Unreferenced 9414 9415This boolean aspect is equivalent to pragma @cite{Unreferenced}. Note that 9416in the case of formal parameters, it is not permitted to have aspects for 9417a formal parameter, so in this case the pragma form must be used. 9418 9419@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 9420@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{11b} 9421@section Aspect Unreferenced_Objects 9422 9423 9424@geindex Unreferenced_Objects 9425 9426This boolean aspect is equivalent to pragma @cite{Unreferenced_Objects}. 9427 9428@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 9429@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{11c} 9430@section Aspect Value_Size 9431 9432 9433@geindex Value_Size 9434 9435This aspect is equivalent to a @cite{Value_Size} 9436attribute definition clause. 9437 9438@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 9439@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{11d} 9440@section Aspect Volatile_Full_Access 9441 9442 9443@geindex Volatile_Full_Access 9444 9445This boolean aspect is equivalent to pragma @cite{Volatile_Full_Access}. 9446 9447@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 9448@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{11e} 9449@section Aspect Volatile_Function 9450 9451 9452@geindex Volatile_Function 9453 9454This boolean aspect is equivalent to pragma @cite{Volatile_Function}. 9455 9456@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 9457@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{11f} 9458@section Aspect Warnings 9459 9460 9461@geindex Warnings 9462 9463This aspect is equivalent to the two argument form of pragma @cite{Warnings}, 9464where the first argument is @cite{ON} or @cite{OFF} and the second argument 9465is the entity. 9466 9467@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 9468@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{120}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{121} 9469@chapter Implementation Defined Attributes 9470 9471 9472Ada defines (throughout the Ada reference manual, 9473summarized in Annex K), 9474a set of attributes that provide useful additional functionality in all 9475areas of the language. These language defined attributes are implemented 9476in GNAT and work as described in the Ada Reference Manual. 9477 9478In addition, Ada allows implementations to define additional 9479attributes whose meaning is defined by the implementation. GNAT provides 9480a number of these implementation-dependent attributes which can be used 9481to extend and enhance the functionality of the compiler. This section of 9482the GNAT reference manual describes these additional attributes. It also 9483describes additional implementation-dependent features of standard 9484language-defined attributes. 9485 9486Note that any program using these attributes may not be portable to 9487other compilers (although GNAT implements this set of attributes on all 9488platforms). Therefore if portability to other compilers is an important 9489consideration, you should minimize the use of these attributes. 9490 9491@menu 9492* Attribute Abort_Signal:: 9493* Attribute Address_Size:: 9494* Attribute Asm_Input:: 9495* Attribute Asm_Output:: 9496* Attribute Atomic_Always_Lock_Free:: 9497* Attribute Bit:: 9498* Attribute Bit_Position:: 9499* Attribute Code_Address:: 9500* Attribute Compiler_Version:: 9501* Attribute Constrained:: 9502* Attribute Default_Bit_Order:: 9503* Attribute Default_Scalar_Storage_Order:: 9504* Attribute Deref:: 9505* Attribute Descriptor_Size:: 9506* Attribute Elaborated:: 9507* Attribute Elab_Body:: 9508* Attribute Elab_Spec:: 9509* Attribute Elab_Subp_Body:: 9510* Attribute Emax:: 9511* Attribute Enabled:: 9512* Attribute Enum_Rep:: 9513* Attribute Enum_Val:: 9514* Attribute Epsilon:: 9515* Attribute Fast_Math:: 9516* Attribute Fixed_Value:: 9517* Attribute From_Any:: 9518* Attribute Has_Access_Values:: 9519* Attribute Has_Discriminants:: 9520* Attribute Img:: 9521* Attribute Integer_Value:: 9522* Attribute Invalid_Value:: 9523* Attribute Iterable:: 9524* Attribute Large:: 9525* Attribute Library_Level:: 9526* Attribute Lock_Free:: 9527* Attribute Loop_Entry:: 9528* Attribute Machine_Size:: 9529* Attribute Mantissa:: 9530* Attribute Maximum_Alignment:: 9531* Attribute Mechanism_Code:: 9532* Attribute Null_Parameter:: 9533* Attribute Object_Size:: 9534* Attribute Old:: 9535* Attribute Passed_By_Reference:: 9536* Attribute Pool_Address:: 9537* Attribute Range_Length:: 9538* Attribute Restriction_Set:: 9539* Attribute Result:: 9540* Attribute Safe_Emax:: 9541* Attribute Safe_Large:: 9542* Attribute Safe_Small:: 9543* Attribute Scalar_Storage_Order:: 9544* Attribute Simple_Storage_Pool:: 9545* Attribute Small:: 9546* Attribute Storage_Unit:: 9547* Attribute Stub_Type:: 9548* Attribute System_Allocator_Alignment:: 9549* Attribute Target_Name:: 9550* Attribute To_Address:: 9551* Attribute To_Any:: 9552* Attribute Type_Class:: 9553* Attribute Type_Key:: 9554* Attribute TypeCode:: 9555* Attribute Unconstrained_Array:: 9556* Attribute Universal_Literal_String:: 9557* Attribute Unrestricted_Access:: 9558* Attribute Update:: 9559* Attribute Valid_Scalars:: 9560* Attribute VADS_Size:: 9561* Attribute Value_Size:: 9562* Attribute Wchar_T_Size:: 9563* Attribute Word_Size:: 9564 9565@end menu 9566 9567@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 9568@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{122} 9569@section Attribute Abort_Signal 9570 9571 9572@geindex Abort_Signal 9573 9574@cite{Standard'Abort_Signal} (@cite{Standard} is the only allowed 9575prefix) provides the entity for the special exception used to signal 9576task abort or asynchronous transfer of control. Normally this attribute 9577should only be used in the tasking runtime (it is highly peculiar, and 9578completely outside the normal semantics of Ada, for a user program to 9579intercept the abort exception). 9580 9581@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 9582@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{123} 9583@section Attribute Address_Size 9584 9585 9586@geindex Size of `Address` 9587 9588@geindex Address_Size 9589 9590@cite{Standard'Address_Size} (@cite{Standard} is the only allowed 9591prefix) is a static constant giving the number of bits in an 9592@cite{Address}. It is the same value as System.Address'Size, 9593but has the advantage of being static, while a direct 9594reference to System.Address'Size is nonstatic because Address 9595is a private type. 9596 9597@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 9598@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{124} 9599@section Attribute Asm_Input 9600 9601 9602@geindex Asm_Input 9603 9604The @cite{Asm_Input} attribute denotes a function that takes two 9605parameters. The first is a string, the second is an expression of the 9606type designated by the prefix. The first (string) argument is required 9607to be a static expression, and is the constraint for the parameter, 9608(e.g., what kind of register is required). The second argument is the 9609value to be used as the input argument. The possible values for the 9610constant are the same as those used in the RTL, and are dependent on 9611the configuration file used to built the GCC back end. 9612@ref{125,,Machine Code Insertions} 9613 9614@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 9615@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{126} 9616@section Attribute Asm_Output 9617 9618 9619@geindex Asm_Output 9620 9621The @cite{Asm_Output} attribute denotes a function that takes two 9622parameters. The first is a string, the second is the name of a variable 9623of the type designated by the attribute prefix. The first (string) 9624argument is required to be a static expression and designates the 9625constraint for the parameter (e.g., what kind of register is 9626required). The second argument is the variable to be updated with the 9627result. The possible values for constraint are the same as those used in 9628the RTL, and are dependent on the configuration file used to build the 9629GCC back end. If there are no output operands, then this argument may 9630either be omitted, or explicitly given as @cite{No_Output_Operands}. 9631@ref{125,,Machine Code Insertions} 9632 9633@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 9634@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{127} 9635@section Attribute Atomic_Always_Lock_Free 9636 9637 9638@geindex Atomic_Always_Lock_Free 9639 9640The prefix of the @cite{Atomic_Always_Lock_Free} attribute is a type. 9641The result is a Boolean value which is True if the type has discriminants, 9642and False otherwise. The result indicate whether atomic operations are 9643supported by the target for the given type. 9644 9645@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 9646@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{128} 9647@section Attribute Bit 9648 9649 9650@geindex Bit 9651 9652@code{obj'Bit}, where @cite{obj} is any object, yields the bit 9653offset within the storage unit (byte) that contains the first bit of 9654storage allocated for the object. The value of this attribute is of the 9655type @cite{Universal_Integer}, and is always a non-negative number not 9656exceeding the value of @cite{System.Storage_Unit}. 9657 9658For an object that is a variable or a constant allocated in a register, 9659the value is zero. (The use of this attribute does not force the 9660allocation of a variable to memory). 9661 9662For an object that is a formal parameter, this attribute applies 9663to either the matching actual parameter or to a copy of the 9664matching actual parameter. 9665 9666For an access object the value is zero. Note that 9667@code{obj.all'Bit} is subject to an @cite{Access_Check} for the 9668designated object. Similarly for a record component 9669@code{X.C'Bit} is subject to a discriminant check and 9670@code{X(I).Bit} and @code{X(I1..I2)'Bit} 9671are subject to index checks. 9672 9673This attribute is designed to be compatible with the DEC Ada 83 definition 9674and implementation of the @cite{Bit} attribute. 9675 9676@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 9677@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{129} 9678@section Attribute Bit_Position 9679 9680 9681@geindex Bit_Position 9682 9683@code{R.C'Bit_Position}, where @cite{R} is a record object and @cite{C} is one 9684of the fields of the record type, yields the bit 9685offset within the record contains the first bit of 9686storage allocated for the object. The value of this attribute is of the 9687type @cite{Universal_Integer}. The value depends only on the field 9688@cite{C} and is independent of the alignment of 9689the containing record @cite{R}. 9690 9691@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 9692@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{12a} 9693@section Attribute Code_Address 9694 9695 9696@geindex Code_Address 9697 9698@geindex Subprogram address 9699 9700@geindex Address of subprogram code 9701 9702The @cite{'Address} 9703attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 9704intended effect seems to be to provide 9705an address value which can be used to call the subprogram by means of 9706an address clause as in the following example: 9707 9708@example 9709procedure K is ... 9710 9711procedure L; 9712for L'Address use K'Address; 9713pragma Import (Ada, L); 9714@end example 9715 9716A call to @cite{L} is then expected to result in a call to @cite{K}. 9717In Ada 83, where there were no access-to-subprogram values, this was 9718a common work-around for getting the effect of an indirect call. 9719GNAT implements the above use of @cite{Address} and the technique 9720illustrated by the example code works correctly. 9721 9722However, for some purposes, it is useful to have the address of the start 9723of the generated code for the subprogram. On some architectures, this is 9724not necessarily the same as the @cite{Address} value described above. 9725For example, the @cite{Address} value may reference a subprogram 9726descriptor rather than the subprogram itself. 9727 9728The @cite{'Code_Address} attribute, which can only be applied to 9729subprogram entities, always returns the address of the start of the 9730generated code of the specified subprogram, which may or may not be 9731the same value as is returned by the corresponding @cite{'Address} 9732attribute. 9733 9734@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 9735@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{12b} 9736@section Attribute Compiler_Version 9737 9738 9739@geindex Compiler_Version 9740 9741@cite{Standard'Compiler_Version} (@cite{Standard} is the only allowed 9742prefix) yields a static string identifying the version of the compiler 9743being used to compile the unit containing the attribute reference. 9744 9745@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 9746@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{12c} 9747@section Attribute Constrained 9748 9749 9750@geindex Constrained 9751 9752In addition to the usage of this attribute in the Ada RM, @cite{GNAT} 9753also permits the use of the @cite{'Constrained} attribute 9754in a generic template 9755for any type, including types without discriminants. The value of this 9756attribute in the generic instance when applied to a scalar type or a 9757record type without discriminants is always @cite{True}. This usage is 9758compatible with older Ada compilers, including notably DEC Ada. 9759 9760@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 9761@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{12d} 9762@section Attribute Default_Bit_Order 9763 9764 9765@geindex Big endian 9766 9767@geindex Little endian 9768 9769@geindex Default_Bit_Order 9770 9771@cite{Standard'Default_Bit_Order} (@cite{Standard} is the only 9772permissible prefix), provides the value @cite{System.Default_Bit_Order} 9773as a @cite{Pos} value (0 for @cite{High_Order_First}, 1 for 9774@cite{Low_Order_First}). This is used to construct the definition of 9775@cite{Default_Bit_Order} in package @cite{System}. 9776 9777@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 9778@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{12e} 9779@section Attribute Default_Scalar_Storage_Order 9780 9781 9782@geindex Big endian 9783 9784@geindex Little endian 9785 9786@geindex Default_Scalar_Storage_Order 9787 9788@cite{Standard'Default_Scalar_Storage_Order} (@cite{Standard} is the only 9789permissible prefix), provides the current value of the default scalar storage 9790order (as specified using pragma @cite{Default_Scalar_Storage_Order}, or 9791equal to @cite{Default_Bit_Order} if unspecified) as a 9792@cite{System.Bit_Order} value. This is a static attribute. 9793 9794@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 9795@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{12f} 9796@section Attribute Deref 9797 9798 9799@geindex Deref 9800 9801The attribute @cite{typ'Deref(expr)} where @cite{expr} is of type @cite{System.Address} yields 9802the variable of type @cite{typ} that is located at the given address. It is similar 9803to @cite{(totyp (expr).all)}, where @cite{totyp} is an unchecked conversion from address to 9804a named access-to-@cite{typ} type, except that it yields a variable, so it can be 9805used on the left side of an assignment. 9806 9807@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 9808@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{130} 9809@section Attribute Descriptor_Size 9810 9811 9812@geindex Descriptor 9813 9814@geindex Dope vector 9815 9816@geindex Descriptor_Size 9817 9818Nonstatic attribute @cite{Descriptor_Size} returns the size in bits of the 9819descriptor allocated for a type. The result is non-zero only for unconstrained 9820array types and the returned value is of type universal integer. In GNAT, an 9821array descriptor contains bounds information and is located immediately before 9822the first element of the array. 9823 9824@example 9825type Unconstr_Array is array (Positive range <>) of Boolean; 9826Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 9827@end example 9828 9829The attribute takes into account any additional padding due to type alignment. 9830In the example above, the descriptor contains two values of type 9831@cite{Positive} representing the low and high bound. Since @cite{Positive} has 9832a size of 31 bits and an alignment of 4, the descriptor size is @cite{2 * Positive'Size + 2} or 64 bits. 9833 9834@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 9835@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{131} 9836@section Attribute Elaborated 9837 9838 9839@geindex Elaborated 9840 9841The prefix of the @cite{'Elaborated} attribute must be a unit name. The 9842value is a Boolean which indicates whether or not the given unit has been 9843elaborated. This attribute is primarily intended for internal use by the 9844generated code for dynamic elaboration checking, but it can also be used 9845in user programs. The value will always be True once elaboration of all 9846units has been completed. An exception is for units which need no 9847elaboration, the value is always False for such units. 9848 9849@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 9850@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{132} 9851@section Attribute Elab_Body 9852 9853 9854@geindex Elab_Body 9855 9856This attribute can only be applied to a program unit name. It returns 9857the entity for the corresponding elaboration procedure for elaborating 9858the body of the referenced unit. This is used in the main generated 9859elaboration procedure by the binder and is not normally used in any 9860other context. However, there may be specialized situations in which it 9861is useful to be able to call this elaboration procedure from Ada code, 9862e.g., if it is necessary to do selective re-elaboration to fix some 9863error. 9864 9865@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 9866@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{133} 9867@section Attribute Elab_Spec 9868 9869 9870@geindex Elab_Spec 9871 9872This attribute can only be applied to a program unit name. It returns 9873the entity for the corresponding elaboration procedure for elaborating 9874the spec of the referenced unit. This is used in the main 9875generated elaboration procedure by the binder and is not normally used 9876in any other context. However, there may be specialized situations in 9877which it is useful to be able to call this elaboration procedure from 9878Ada code, e.g., if it is necessary to do selective re-elaboration to fix 9879some error. 9880 9881@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 9882@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{134} 9883@section Attribute Elab_Subp_Body 9884 9885 9886@geindex Elab_Subp_Body 9887 9888This attribute can only be applied to a library level subprogram 9889name and is only allowed in CodePeer mode. It returns the entity 9890for the corresponding elaboration procedure for elaborating the body 9891of the referenced subprogram unit. This is used in the main generated 9892elaboration procedure by the binder in CodePeer mode only and is unrecognized 9893otherwise. 9894 9895@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 9896@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{135} 9897@section Attribute Emax 9898 9899 9900@geindex Ada 83 attributes 9901 9902@geindex Emax 9903 9904The @cite{Emax} attribute is provided for compatibility with Ada 83. See 9905the Ada 83 reference manual for an exact description of the semantics of 9906this attribute. 9907 9908@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 9909@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{136} 9910@section Attribute Enabled 9911 9912 9913@geindex Enabled 9914 9915The @cite{Enabled} attribute allows an application program to check at compile 9916time to see if the designated check is currently enabled. The prefix is a 9917simple identifier, referencing any predefined check name (other than 9918@cite{All_Checks}) or a check name introduced by pragma Check_Name. If 9919no argument is given for the attribute, the check is for the general state 9920of the check, if an argument is given, then it is an entity name, and the 9921check indicates whether an @cite{Suppress} or @cite{Unsuppress} has been 9922given naming the entity (if not, then the argument is ignored). 9923 9924Note that instantiations inherit the check status at the point of the 9925instantiation, so a useful idiom is to have a library package that 9926introduces a check name with @cite{pragma Check_Name}, and then contains 9927generic packages or subprograms which use the @cite{Enabled} attribute 9928to see if the check is enabled. A user of this package can then issue 9929a @cite{pragma Suppress} or @cite{pragma Unsuppress} before instantiating 9930the package or subprogram, controlling whether the check will be present. 9931 9932@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 9933@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{137} 9934@section Attribute Enum_Rep 9935 9936 9937@geindex Representation of enums 9938 9939@geindex Enum_Rep 9940 9941For every enumeration subtype @cite{S}, @code{S'Enum_Rep} denotes a 9942function with the following spec: 9943 9944@example 9945function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 9946@end example 9947 9948It is also allowable to apply @cite{Enum_Rep} directly to an object of an 9949enumeration type or to a non-overloaded enumeration 9950literal. In this case @code{S'Enum_Rep} is equivalent to 9951@code{typ'Enum_Rep(S)} where @cite{typ} is the type of the 9952enumeration literal or object. 9953 9954The function returns the representation value for the given enumeration 9955value. This will be equal to value of the @cite{Pos} attribute in the 9956absence of an enumeration representation clause. This is a static 9957attribute (i.e.,:the result is static if the argument is static). 9958 9959@code{S'Enum_Rep} can also be used with integer types and objects, 9960in which case it simply returns the integer value. The reason for this 9961is to allow it to be used for @cite{(<>)} discrete formal arguments in 9962a generic unit that can be instantiated with either enumeration types 9963or integer types. Note that if @cite{Enum_Rep} is used on a modular 9964type whose upper bound exceeds the upper bound of the largest signed 9965integer type, and the argument is a variable, so that the universal 9966integer calculation is done at run time, then the call to @cite{Enum_Rep} 9967may raise @cite{Constraint_Error}. 9968 9969@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 9970@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{138} 9971@section Attribute Enum_Val 9972 9973 9974@geindex Representation of enums 9975 9976@geindex Enum_Val 9977 9978For every enumeration subtype @cite{S}, @code{S'Enum_Val} denotes a 9979function with the following spec: 9980 9981@example 9982function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 9983@end example 9984 9985The function returns the enumeration value whose representation matches the 9986argument, or raises Constraint_Error if no enumeration literal of the type 9987has the matching value. 9988This will be equal to value of the @cite{Val} attribute in the 9989absence of an enumeration representation clause. This is a static 9990attribute (i.e., the result is static if the argument is static). 9991 9992@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 9993@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{139} 9994@section Attribute Epsilon 9995 9996 9997@geindex Ada 83 attributes 9998 9999@geindex Epsilon 10000 10001The @cite{Epsilon} attribute is provided for compatibility with Ada 83. See 10002the Ada 83 reference manual for an exact description of the semantics of 10003this attribute. 10004 10005@node Attribute Fast_Math,Attribute Fixed_Value,Attribute Epsilon,Implementation Defined Attributes 10006@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{13a} 10007@section Attribute Fast_Math 10008 10009 10010@geindex Fast_Math 10011 10012@cite{Standard'Fast_Math} (@cite{Standard} is the only allowed 10013prefix) yields a static Boolean value that is True if pragma 10014@cite{Fast_Math} is active, and False otherwise. 10015 10016@node Attribute Fixed_Value,Attribute From_Any,Attribute Fast_Math,Implementation Defined Attributes 10017@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{13b} 10018@section Attribute Fixed_Value 10019 10020 10021@geindex Fixed_Value 10022 10023For every fixed-point type @cite{S}, @code{S'Fixed_Value} denotes a 10024function with the following specification: 10025 10026@example 10027function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10028@end example 10029 10030The value returned is the fixed-point value @cite{V} such that: 10031 10032@example 10033V = Arg * S'Small 10034@end example 10035 10036The effect is thus similar to first converting the argument to the 10037integer type used to represent @cite{S}, and then doing an unchecked 10038conversion to the fixed-point type. The difference is 10039that there are full range checks, to ensure that the result is in range. 10040This attribute is primarily intended for use in implementation of the 10041input-output functions for fixed-point values. 10042 10043@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10044@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{13c} 10045@section Attribute From_Any 10046 10047 10048@geindex From_Any 10049 10050This internal attribute is used for the generation of remote subprogram 10051stubs in the context of the Distributed Systems Annex. 10052 10053@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10054@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{13d} 10055@section Attribute Has_Access_Values 10056 10057 10058@geindex Access values 10059@geindex testing for 10060 10061@geindex Has_Access_Values 10062 10063The prefix of the @cite{Has_Access_Values} attribute is a type. The result 10064is a Boolean value which is True if the is an access type, or is a composite 10065type with a component (at any nesting depth) that is an access type, and is 10066False otherwise. 10067The intended use of this attribute is in conjunction with generic 10068definitions. If the attribute is applied to a generic private type, it 10069indicates whether or not the corresponding actual type has access values. 10070 10071@node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes 10072@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{13e} 10073@section Attribute Has_Discriminants 10074 10075 10076@geindex Discriminants 10077@geindex testing for 10078 10079@geindex Has_Discriminants 10080 10081The prefix of the @cite{Has_Discriminants} attribute is a type. The result 10082is a Boolean value which is True if the type has discriminants, and False 10083otherwise. The intended use of this attribute is in conjunction with generic 10084definitions. If the attribute is applied to a generic private type, it 10085indicates whether or not the corresponding actual type has discriminants. 10086 10087@node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes 10088@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{13f} 10089@section Attribute Img 10090 10091 10092@geindex Img 10093 10094The @cite{Img} attribute differs from @cite{Image} in that it is applied 10095directly to an object, and yields the same result as 10096@cite{Image} for the subtype of the object. This is convenient for 10097debugging: 10098 10099@example 10100Put_Line ("X = " & X'Img); 10101@end example 10102 10103has the same meaning as the more verbose: 10104 10105@example 10106Put_Line ("X = " & T'Image (X)); 10107@end example 10108 10109where @cite{T} is the (sub)type of the object @cite{X}. 10110 10111Note that technically, in analogy to @cite{Image}, 10112@cite{X'Img} returns a parameterless function 10113that returns the appropriate string when called. This means that 10114@cite{X'Img} can be renamed as a function-returning-string, or used 10115in an instantiation as a function parameter. 10116 10117@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes 10118@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{140} 10119@section Attribute Integer_Value 10120 10121 10122@geindex Integer_Value 10123 10124For every integer type @cite{S}, @code{S'Integer_Value} denotes a 10125function with the following spec: 10126 10127@example 10128function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10129@end example 10130 10131The value returned is the integer value @cite{V}, such that: 10132 10133@example 10134Arg = V * T'Small 10135@end example 10136 10137where @cite{T} is the type of @cite{Arg}. 10138The effect is thus similar to first doing an unchecked conversion from 10139the fixed-point type to its corresponding implementation type, and then 10140converting the result to the target integer type. The difference is 10141that there are full range checks, to ensure that the result is in range. 10142This attribute is primarily intended for use in implementation of the 10143standard input-output functions for fixed-point values. 10144 10145@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10146@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{141} 10147@section Attribute Invalid_Value 10148 10149 10150@geindex Invalid_Value 10151 10152For every scalar type S, S'Invalid_Value returns an undefined value of the 10153type. If possible this value is an invalid representation for the type. The 10154value returned is identical to the value used to initialize an otherwise 10155uninitialized value of the type if pragma Initialize_Scalars is used, 10156including the ability to modify the value with the binder -Sxx flag and 10157relevant environment variables at run time. 10158 10159@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10160@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{142} 10161@section Attribute Iterable 10162 10163 10164@geindex Iterable 10165 10166Equivalent to Aspect Iterable. 10167 10168@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10169@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{143} 10170@section Attribute Large 10171 10172 10173@geindex Ada 83 attributes 10174 10175@geindex Large 10176 10177The @cite{Large} attribute is provided for compatibility with Ada 83. See 10178the Ada 83 reference manual for an exact description of the semantics of 10179this attribute. 10180 10181@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10182@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{144} 10183@section Attribute Library_Level 10184 10185 10186@geindex Library_Level 10187 10188@cite{P'Library_Level}, where P is an entity name, 10189returns a Boolean value which is True if the entity is declared 10190at the library level, and False otherwise. Note that within a 10191generic instantition, the name of the generic unit denotes the 10192instance, which means that this attribute can be used to test 10193if a generic is instantiated at the library level, as shown 10194in this example: 10195 10196@example 10197generic 10198 ... 10199package Gen is 10200 pragma Compile_Time_Error 10201 (not Gen'Library_Level, 10202 "Gen can only be instantiated at library level"); 10203 ... 10204end Gen; 10205@end example 10206 10207@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10208@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{145} 10209@section Attribute Lock_Free 10210 10211 10212@geindex Lock_Free 10213 10214@cite{P'Lock_Free}, where P is a protected object, returns True if a 10215pragma @cite{Lock_Free} applies to P. 10216 10217@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 10218@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{146} 10219@section Attribute Loop_Entry 10220 10221 10222@geindex Loop_Entry 10223 10224Syntax: 10225 10226@example 10227X'Loop_Entry [(loop_name)] 10228@end example 10229 10230The @cite{Loop_Entry} attribute is used to refer to the value that an 10231expression had upon entry to a given loop in much the same way that the 10232@cite{Old} attribute in a subprogram postcondition can be used to refer 10233to the value an expression had upon entry to the subprogram. The 10234relevant loop is either identified by the given loop name, or it is the 10235innermost enclosing loop when no loop name is given. 10236 10237A @cite{Loop_Entry} attribute can only occur within a 10238@cite{Loop_Variant} or @cite{Loop_Invariant} pragma. A common use of 10239@cite{Loop_Entry} is to compare the current value of objects with their 10240initial value at loop entry, in a @cite{Loop_Invariant} pragma. 10241 10242The effect of using @cite{X'Loop_Entry} is the same as declaring 10243a constant initialized with the initial value of @cite{X} at loop 10244entry. This copy is not performed if the loop is not entered, or if the 10245corresponding pragmas are ignored or disabled. 10246 10247@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 10248@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{147} 10249@section Attribute Machine_Size 10250 10251 10252@geindex Machine_Size 10253 10254This attribute is identical to the @cite{Object_Size} attribute. It is 10255provided for compatibility with the DEC Ada 83 attribute of this name. 10256 10257@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 10258@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{148} 10259@section Attribute Mantissa 10260 10261 10262@geindex Ada 83 attributes 10263 10264@geindex Mantissa 10265 10266The @cite{Mantissa} attribute is provided for compatibility with Ada 83. See 10267the Ada 83 reference manual for an exact description of the semantics of 10268this attribute. 10269 10270@node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes 10271@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{149}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{14a} 10272@section Attribute Maximum_Alignment 10273 10274 10275@geindex Alignment 10276@geindex maximum 10277 10278@geindex Maximum_Alignment 10279 10280@cite{Standard'Maximum_Alignment} (@cite{Standard} is the only 10281permissible prefix) provides the maximum useful alignment value for the 10282target. This is a static value that can be used to specify the alignment 10283for an object, guaranteeing that it is properly aligned in all 10284cases. 10285 10286@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes 10287@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{14b} 10288@section Attribute Mechanism_Code 10289 10290 10291@geindex Return values 10292@geindex passing mechanism 10293 10294@geindex Parameters 10295@geindex passing mechanism 10296 10297@geindex Mechanism_Code 10298 10299@code{function'Mechanism_Code} yields an integer code for the 10300mechanism used for the result of function, and 10301@code{subprogram'Mechanism_Code (n)} yields the mechanism 10302used for formal parameter number @cite{n} (a static integer value with 1 10303meaning the first parameter) of @cite{subprogram}. The code returned is: 10304 10305 10306@table @asis 10307 10308@item @emph{1} 10309 10310by copy (value) 10311 10312@item @emph{2} 10313 10314by reference 10315@end table 10316 10317@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 10318@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{14c} 10319@section Attribute Null_Parameter 10320 10321 10322@geindex Zero address 10323@geindex passing 10324 10325@geindex Null_Parameter 10326 10327A reference @code{T'Null_Parameter} denotes an imaginary object of 10328type or subtype @cite{T} allocated at machine address zero. The attribute 10329is allowed only as the default expression of a formal parameter, or as 10330an actual expression of a subprogram call. In either case, the 10331subprogram must be imported. 10332 10333The identity of the object is represented by the address zero in the 10334argument list, independent of the passing mechanism (explicit or 10335default). 10336 10337This capability is needed to specify that a zero address should be 10338passed for a record or other composite object passed by reference. 10339There is no way of indicating this without the @cite{Null_Parameter} 10340attribute. 10341 10342@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 10343@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{14d} 10344@section Attribute Object_Size 10345 10346 10347@geindex Size 10348@geindex used for objects 10349 10350@geindex Object_Size 10351 10352The size of an object is not necessarily the same as the size of the type 10353of an object. This is because by default object sizes are increased to be 10354a multiple of the alignment of the object. For example, 10355@cite{Natural'Size} is 1035631, but by default objects of type @cite{Natural} will have a size of 32 bits. 10357Similarly, a record containing an integer and a character: 10358 10359@example 10360type Rec is record 10361 I : Integer; 10362 C : Character; 10363end record; 10364@end example 10365 10366will have a size of 40 (that is @cite{Rec'Size} will be 40). The 10367alignment will be 4, because of the 10368integer field, and so the default size of record objects for this type 10369will be 64 (8 bytes). 10370 10371If the alignment of the above record is specified to be 1, then the 10372object size will be 40 (5 bytes). This is true by default, and also 10373an object size of 40 can be explicitly specified in this case. 10374 10375A consequence of this capability is that different object sizes can be 10376given to subtypes that would otherwise be considered in Ada to be 10377statically matching. But it makes no sense to consider such subtypes 10378as statically matching. Consequently, in @cite{GNAT} we add a rule 10379to the static matching rules that requires object sizes to match. 10380Consider this example: 10381 10382@example 10383 1. procedure BadAVConvert is 10384 2. type R is new Integer; 10385 3. subtype R1 is R range 1 .. 10; 10386 4. subtype R2 is R range 1 .. 10; 10387 5. for R1'Object_Size use 8; 10388 6. for R2'Object_Size use 16; 10389 7. type R1P is access all R1; 10390 8. type R2P is access all R2; 10391 9. R1PV : R1P := new R1'(4); 1039210. R2PV : R2P; 1039311. begin 1039412. R2PV := R2P (R1PV); 10395 | 10396 >>> target designated subtype not compatible with 10397 type "R1" defined at line 3 10398 1039913. end; 10400@end example 10401 10402In the absence of lines 5 and 6, 10403types @cite{R1} and @cite{R2} statically match and 10404hence the conversion on line 12 is legal. But since lines 5 and 6 10405cause the object sizes to differ, @cite{GNAT} considers that types 10406@cite{R1} and @cite{R2} are not statically matching, and line 12 10407generates the diagnostic shown above. 10408 10409Similar additional checks are performed in other contexts requiring 10410statically matching subtypes. 10411 10412@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 10413@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{14e} 10414@section Attribute Old 10415 10416 10417@geindex Old 10418 10419In addition to the usage of @cite{Old} defined in the Ada 2012 RM (usage 10420within @cite{Post} aspect), GNAT also permits the use of this attribute 10421in implementation defined pragmas @cite{Postcondition}, 10422@cite{Contract_Cases} and @cite{Test_Case}. Also usages of 10423@cite{Old} which would be illegal according to the Ada 2012 RM 10424definition are allowed under control of 10425implementation defined pragma @cite{Unevaluated_Use_Of_Old}. 10426 10427@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 10428@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{14f} 10429@section Attribute Passed_By_Reference 10430 10431 10432@geindex Parameters 10433@geindex when passed by reference 10434 10435@geindex Passed_By_Reference 10436 10437@code{type'Passed_By_Reference} for any subtype @cite{type} returns 10438a value of type @cite{Boolean} value that is @cite{True} if the type is 10439normally passed by reference and @cite{False} if the type is normally 10440passed by copy in calls. For scalar types, the result is always @cite{False} 10441and is static. For non-scalar types, the result is nonstatic. 10442 10443@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 10444@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{150} 10445@section Attribute Pool_Address 10446 10447 10448@geindex Parameters 10449@geindex when passed by reference 10450 10451@geindex Pool_Address 10452 10453@code{X'Pool_Address} for any object @cite{X} returns the address 10454of X within its storage pool. This is the same as 10455@code{X'Address}, except that for an unconstrained array whose 10456bounds are allocated just before the first component, 10457@code{X'Pool_Address} returns the address of those bounds, 10458whereas @code{X'Address} returns the address of the first 10459component. 10460 10461Here, we are interpreting 'storage pool' broadly to mean 10462@code{wherever the object is allocated}, which could be a 10463user-defined storage pool, 10464the global heap, on the stack, or in a static memory area. 10465For an object created by @cite{new}, @code{Ptr.all'Pool_Address} is 10466what is passed to @cite{Allocate} and returned from @cite{Deallocate}. 10467 10468@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 10469@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{151} 10470@section Attribute Range_Length 10471 10472 10473@geindex Range_Length 10474 10475@code{type'Range_Length} for any discrete type @cite{type} yields 10476the number of values represented by the subtype (zero for a null 10477range). The result is static for static subtypes. @cite{Range_Length} 10478applied to the index subtype of a one dimensional array always gives the 10479same result as @cite{Length} applied to the array itself. 10480 10481@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 10482@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{152} 10483@section Attribute Restriction_Set 10484 10485 10486@geindex Restriction_Set 10487 10488@geindex Restrictions 10489 10490This attribute allows compile time testing of restrictions that 10491are currently in effect. It is primarily intended for specializing 10492code in the run-time based on restrictions that are active (e.g. 10493don't need to save fpt registers if restriction No_Floating_Point 10494is known to be in effect), but can be used anywhere. 10495 10496There are two forms: 10497 10498@example 10499System'Restriction_Set (partition_boolean_restriction_NAME) 10500System'Restriction_Set (No_Dependence => library_unit_NAME); 10501@end example 10502 10503In the case of the first form, the only restriction names 10504allowed are parameterless restrictions that are checked 10505for consistency at bind time. For a complete list see the 10506subtype @cite{System.Rident.Partition_Boolean_Restrictions}. 10507 10508The result returned is True if the restriction is known to 10509be in effect, and False if the restriction is known not to 10510be in effect. An important guarantee is that the value of 10511a Restriction_Set attribute is known to be consistent throughout 10512all the code of a partition. 10513 10514This is trivially achieved if the entire partition is compiled 10515with a consistent set of restriction pragmas. However, the 10516compilation model does not require this. It is possible to 10517compile one set of units with one set of pragmas, and another 10518set of units with another set of pragmas. It is even possible 10519to compile a spec with one set of pragmas, and then WITH the 10520same spec with a different set of pragmas. Inconsistencies 10521in the actual use of the restriction are checked at bind time. 10522 10523In order to achieve the guarantee of consistency for the 10524Restriction_Set pragma, we consider that a use of the pragma 10525that yields False is equivalent to a violation of the 10526restriction. 10527 10528So for example if you write 10529 10530@example 10531if System'Restriction_Set (No_Floating_Point) then 10532 ... 10533else 10534 ... 10535end if; 10536@end example 10537 10538And the result is False, so that the else branch is executed, 10539you can assume that this restriction is not set for any unit 10540in the partition. This is checked by considering this use of 10541the restriction pragma to be a violation of the restriction 10542No_Floating_Point. This means that no other unit can attempt 10543to set this restriction (if some unit does attempt to set it, 10544the binder will refuse to bind the partition). 10545 10546Technical note: The restriction name and the unit name are 10547intepreted entirely syntactically, as in the corresponding 10548Restrictions pragma, they are not analyzed semantically, 10549so they do not have a type. 10550 10551@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 10552@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{153} 10553@section Attribute Result 10554 10555 10556@geindex Result 10557 10558@code{function'Result} can only be used with in a Postcondition pragma 10559for a function. The prefix must be the name of the corresponding function. This 10560is used to refer to the result of the function in the postcondition expression. 10561For a further discussion of the use of this attribute and examples of its use, 10562see the description of pragma Postcondition. 10563 10564@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 10565@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{154} 10566@section Attribute Safe_Emax 10567 10568 10569@geindex Ada 83 attributes 10570 10571@geindex Safe_Emax 10572 10573The @cite{Safe_Emax} attribute is provided for compatibility with Ada 83. See 10574the Ada 83 reference manual for an exact description of the semantics of 10575this attribute. 10576 10577@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 10578@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{155} 10579@section Attribute Safe_Large 10580 10581 10582@geindex Ada 83 attributes 10583 10584@geindex Safe_Large 10585 10586The @cite{Safe_Large} attribute is provided for compatibility with Ada 83. See 10587the Ada 83 reference manual for an exact description of the semantics of 10588this attribute. 10589 10590@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 10591@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{156} 10592@section Attribute Safe_Small 10593 10594 10595@geindex Ada 83 attributes 10596 10597@geindex Safe_Small 10598 10599The @cite{Safe_Small} attribute is provided for compatibility with Ada 83. See 10600the Ada 83 reference manual for an exact description of the semantics of 10601this attribute. 10602 10603@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 10604@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{157} 10605@section Attribute Scalar_Storage_Order 10606 10607 10608@geindex Endianness 10609 10610@geindex Scalar storage order 10611 10612@geindex Scalar_Storage_Order 10613 10614For every array or record type @cite{S}, the representation attribute 10615@cite{Scalar_Storage_Order} denotes the order in which storage elements 10616that make up scalar components are ordered within S. The value given must 10617be a static expression of type System.Bit_Order. The following is an example 10618of the use of this feature: 10619 10620@example 10621-- Component type definitions 10622 10623subtype Yr_Type is Natural range 0 .. 127; 10624subtype Mo_Type is Natural range 1 .. 12; 10625subtype Da_Type is Natural range 1 .. 31; 10626 10627-- Record declaration 10628 10629type Date is record 10630 Years_Since_1980 : Yr_Type; 10631 Month : Mo_Type; 10632 Day_Of_Month : Da_Type; 10633end record; 10634 10635-- Record representation clause 10636 10637for Date use record 10638 Years_Since_1980 at 0 range 0 .. 6; 10639 Month at 0 range 7 .. 10; 10640 Day_Of_Month at 0 range 11 .. 15; 10641end record; 10642 10643-- Attribute definition clauses 10644 10645for Date'Bit_Order use System.High_Order_First; 10646for Date'Scalar_Storage_Order use System.High_Order_First; 10647-- If Scalar_Storage_Order is specified, it must be consistent with 10648-- Bit_Order, so it's best to always define the latter explicitly if 10649-- the former is used. 10650@end example 10651 10652Other properties are as for standard representation attribute @cite{Bit_Order}, 10653as defined by Ada RM 13.5.3(4). The default is @cite{System.Default_Bit_Order}. 10654 10655For a record type @cite{T}, if @code{T'Scalar_Storage_Order} is 10656specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 10657this means that if a @cite{Scalar_Storage_Order} attribute definition 10658clause is not confirming, then the type's @cite{Bit_Order} shall be 10659specified explicitly and set to the same value. 10660 10661Derived types inherit an explicitly set scalar storage order from their parent 10662types. This may be overridden for the derived type by giving an explicit scalar 10663storage order for the derived type. For a record extension, the derived type 10664must have the same scalar storage order as the parent type. 10665 10666If a component of @cite{T} is of a record or array type, then that type must 10667also have a @cite{Scalar_Storage_Order} attribute definition clause. 10668 10669A component of a record or array type that is a packed array, or that 10670does not start on a byte boundary, must have the same scalar storage order 10671as the enclosing record or array type. 10672 10673No component of a type that has an explicit @cite{Scalar_Storage_Order} 10674attribute definition may be aliased. 10675 10676A confirming @cite{Scalar_Storage_Order} attribute definition clause (i.e. 10677with a value equal to @cite{System.Default_Bit_Order}) has no effect. 10678 10679If the opposite storage order is specified, then whenever the value of 10680a scalar component of an object of type @cite{S} is read, the storage 10681elements of the enclosing machine scalar are first reversed (before 10682retrieving the component value, possibly applying some shift and mask 10683operatings on the enclosing machine scalar), and the opposite operation 10684is done for writes. 10685 10686In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 10687are relaxed. Instead, the following rules apply: 10688 10689 10690@itemize * 10691 10692@item 10693the underlying storage elements are those at positions 10694@cite{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 10695 10696@item 10697the sequence of underlying storage elements shall have 10698a size no greater than the largest machine scalar 10699 10700@item 10701the enclosing machine scalar is defined as the smallest machine 10702scalar starting at a position no greater than 10703@cite{position + first_bit / storage_element_size} and covering 10704storage elements at least up to @cite{position + (last_bit + storage_element_size - 1) / storage_element_size} 10705 10706@item 10707the position of the component is interpreted relative to that machine 10708scalar. 10709@end itemize 10710 10711If no scalar storage order is specified for a type (either directly, or by 10712inheritance in the case of a derived type), then the default is normally 10713the native ordering of the target, but this default can be overridden using 10714pragma @cite{Default_Scalar_Storage_Order}. 10715 10716Note that the scalar storage order only affects the in-memory data 10717representation. It has no effect on the representation used by stream 10718attributes. 10719 10720@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 10721@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{b9}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{158} 10722@section Attribute Simple_Storage_Pool 10723 10724 10725@geindex Storage pool 10726@geindex simple 10727 10728@geindex Simple storage pool 10729 10730@geindex Simple_Storage_Pool 10731 10732For every nonformal, nonderived access-to-object type @cite{Acc}, the 10733representation attribute @cite{Simple_Storage_Pool} may be specified 10734via an attribute_definition_clause (or by specifying the equivalent aspect): 10735 10736@example 10737My_Pool : My_Simple_Storage_Pool_Type; 10738 10739type Acc is access My_Data_Type; 10740 10741for Acc'Simple_Storage_Pool use My_Pool; 10742@end example 10743 10744The name given in an attribute_definition_clause for the 10745@cite{Simple_Storage_Pool} attribute shall denote a variable of 10746a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}). 10747 10748The use of this attribute is only allowed for a prefix denoting a type 10749for which it has been specified. The type of the attribute is the type 10750of the variable specified as the simple storage pool of the access type, 10751and the attribute denotes that variable. 10752 10753It is illegal to specify both @cite{Storage_Pool} and @cite{Simple_Storage_Pool} 10754for the same access type. 10755 10756If the @cite{Simple_Storage_Pool} attribute has been specified for an access 10757type, then applying the @cite{Storage_Pool} attribute to the type is flagged 10758with a warning and its evaluation raises the exception @cite{Program_Error}. 10759 10760If the Simple_Storage_Pool attribute has been specified for an access 10761type @cite{S}, then the evaluation of the attribute @code{S'Storage_Size} 10762returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 10763which is intended to indicate the number of storage elements reserved for 10764the simple storage pool. If the Storage_Size function has not been defined 10765for the simple storage pool type, then this attribute returns zero. 10766 10767If an access type @cite{S} has a specified simple storage pool of type 10768@cite{SSP}, then the evaluation of an allocator for that access type calls 10769the primitive @cite{Allocate} procedure for type @cite{SSP}, passing 10770@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 10771semantics of such allocators is the same as those defined for allocators 10772in section 13.11 of the @cite{Ada Reference Manual}, with the term 10773@cite{simple storage pool} substituted for @cite{storage pool}. 10774 10775If an access type @cite{S} has a specified simple storage pool of type 10776@cite{SSP}, then a call to an instance of the @cite{Ada.Unchecked_Deallocation} 10777for that access type invokes the primitive @cite{Deallocate} procedure 10778for type @cite{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 10779parameter. The detailed semantics of such unchecked deallocations is the same 10780as defined in section 13.11.2 of the Ada Reference Manual, except that the 10781term 'simple storage pool' is substituted for 'storage pool'. 10782 10783@node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes 10784@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{159} 10785@section Attribute Small 10786 10787 10788@geindex Ada 83 attributes 10789 10790@geindex Small 10791 10792The @cite{Small} attribute is defined in Ada 95 (and Ada 2005) only for 10793fixed-point types. 10794GNAT also allows this attribute to be applied to floating-point types 10795for compatibility with Ada 83. See 10796the Ada 83 reference manual for an exact description of the semantics of 10797this attribute when applied to floating-point types. 10798 10799@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes 10800@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{15a} 10801@section Attribute Storage_Unit 10802 10803 10804@geindex Storage_Unit 10805 10806@cite{Standard'Storage_Unit} (@cite{Standard} is the only permissible 10807prefix) provides the same value as @cite{System.Storage_Unit}. 10808 10809@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 10810@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{15b} 10811@section Attribute Stub_Type 10812 10813 10814@geindex Stub_Type 10815 10816The GNAT implementation of remote access-to-classwide types is 10817organized as described in AARM section E.4 (20.t): a value of an RACW type 10818(designating a remote object) is represented as a normal access 10819value, pointing to a "stub" object which in turn contains the 10820necessary information to contact the designated remote object. A 10821call on any dispatching operation of such a stub object does the 10822remote call, if necessary, using the information in the stub object 10823to locate the target partition, etc. 10824 10825For a prefix @cite{T} that denotes a remote access-to-classwide type, 10826@cite{T'Stub_Type} denotes the type of the corresponding stub objects. 10827 10828By construction, the layout of @cite{T'Stub_Type} is identical to that of 10829type @cite{RACW_Stub_Type} declared in the internal implementation-defined 10830unit @cite{System.Partition_Interface}. Use of this attribute will create 10831an implicit dependency on this unit. 10832 10833@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 10834@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{15c} 10835@section Attribute System_Allocator_Alignment 10836 10837 10838@geindex Alignment 10839@geindex allocator 10840 10841@geindex System_Allocator_Alignment 10842 10843@cite{Standard'System_Allocator_Alignment} (@cite{Standard} is the only 10844permissible prefix) provides the observable guaranted to be honored by 10845the system allocator (malloc). This is a static value that can be used 10846in user storage pools based on malloc either to reject allocation 10847with alignment too large or to enable a realignment circuitry if the 10848alignment request is larger than this value. 10849 10850@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 10851@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{15d} 10852@section Attribute Target_Name 10853 10854 10855@geindex Target_Name 10856 10857@cite{Standard'Target_Name} (@cite{Standard} is the only permissible 10858prefix) provides a static string value that identifies the target 10859for the current compilation. For GCC implementations, this is the 10860standard gcc target name without the terminating slash (for 10861example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 10862 10863@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 10864@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{15e} 10865@section Attribute To_Address 10866 10867 10868@geindex To_Address 10869 10870The @cite{System'To_Address} 10871(@cite{System} is the only permissible prefix) 10872denotes a function identical to 10873@cite{System.Storage_Elements.To_Address} except that 10874it is a static attribute. This means that if its argument is 10875a static expression, then the result of the attribute is a 10876static expression. This means that such an expression can be 10877used in contexts (e.g., preelaborable packages) which require a 10878static expression and where the function call could not be used 10879(since the function call is always nonstatic, even if its 10880argument is static). The argument must be in the range 10881-(2**(m-1) .. 2**m-1, where m is the memory size 10882(typically 32 or 64). Negative values are intepreted in a 10883modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 10884a 32 bits machine). 10885 10886@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 10887@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{15f} 10888@section Attribute To_Any 10889 10890 10891@geindex To_Any 10892 10893This internal attribute is used for the generation of remote subprogram 10894stubs in the context of the Distributed Systems Annex. 10895 10896@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 10897@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{160} 10898@section Attribute Type_Class 10899 10900 10901@geindex Type_Class 10902 10903@code{type'Type_Class} for any type or subtype @cite{type} yields 10904the value of the type class for the full type of @cite{type}. If 10905@cite{type} is a generic formal type, the value is the value for the 10906corresponding actual subtype. The value of this attribute is of type 10907@code{System.Aux_DEC.Type_Class}, which has the following definition: 10908 10909@example 10910type Type_Class is 10911 (Type_Class_Enumeration, 10912 Type_Class_Integer, 10913 Type_Class_Fixed_Point, 10914 Type_Class_Floating_Point, 10915 Type_Class_Array, 10916 Type_Class_Record, 10917 Type_Class_Access, 10918 Type_Class_Task, 10919 Type_Class_Address); 10920@end example 10921 10922Protected types yield the value @cite{Type_Class_Task}, which thus 10923applies to all concurrent types. This attribute is designed to 10924be compatible with the DEC Ada 83 attribute of the same name. 10925 10926@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 10927@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{161} 10928@section Attribute Type_Key 10929 10930 10931@geindex Type_Key 10932 10933The @cite{Type_Key} attribute is applicable to a type or subtype and 10934yields a value of type Standard.String containing encoded information 10935about the type or subtype. This provides improved compatibility with 10936other implementations that support this attribute. 10937 10938@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 10939@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{162} 10940@section Attribute TypeCode 10941 10942 10943@geindex TypeCode 10944 10945This internal attribute is used for the generation of remote subprogram 10946stubs in the context of the Distributed Systems Annex. 10947 10948@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 10949@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{163} 10950@section Attribute Unconstrained_Array 10951 10952 10953@geindex Unconstrained_Array 10954 10955The @cite{Unconstrained_Array} attribute can be used with a prefix that 10956denotes any type or subtype. It is a static attribute that yields 10957@cite{True} if the prefix designates an unconstrained array, 10958and @cite{False} otherwise. In a generic instance, the result is 10959still static, and yields the result of applying this test to the 10960generic actual. 10961 10962@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 10963@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{164} 10964@section Attribute Universal_Literal_String 10965 10966 10967@geindex Named numbers 10968@geindex representation of 10969 10970@geindex Universal_Literal_String 10971 10972The prefix of @cite{Universal_Literal_String} must be a named 10973number. The static result is the string consisting of the characters of 10974the number as defined in the original source. This allows the user 10975program to access the actual text of named numbers without intermediate 10976conversions and without the need to enclose the strings in quotes (which 10977would preclude their use as numbers). 10978 10979For example, the following program prints the first 50 digits of pi: 10980 10981@example 10982with Text_IO; use Text_IO; 10983with Ada.Numerics; 10984procedure Pi is 10985begin 10986 Put (Ada.Numerics.Pi'Universal_Literal_String); 10987end; 10988@end example 10989 10990@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 10991@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{165} 10992@section Attribute Unrestricted_Access 10993 10994 10995@geindex Access 10996@geindex unrestricted 10997 10998@geindex Unrestricted_Access 10999 11000The @cite{Unrestricted_Access} attribute is similar to @cite{Access} 11001except that all accessibility and aliased view checks are omitted. This 11002is a user-beware attribute. 11003 11004For objects, it is similar to @cite{Address}, for which it is a 11005desirable replacement where the value desired is an access type. 11006In other words, its effect is similar to first applying the 11007@cite{Address} attribute and then doing an unchecked conversion to a 11008desired access type. 11009 11010For subprograms, @cite{P'Unrestricted_Access} may be used where 11011@cite{P'Access} would be illegal, to construct a value of a 11012less-nested named access type that designates a more-nested 11013subprogram. This value may be used in indirect calls, so long as the 11014more-nested subprogram still exists; once the subprogram containing it 11015has returned, such calls are erroneous. For example: 11016 11017@example 11018package body P is 11019 11020 type Less_Nested is not null access procedure; 11021 Global : Less_Nested; 11022 11023 procedure P1 is 11024 begin 11025 Global.all; 11026 end P1; 11027 11028 procedure P2 is 11029 Local_Var : Integer; 11030 11031 procedure More_Nested is 11032 begin 11033 ... Local_Var ... 11034 end More_Nested; 11035 begin 11036 Global := More_Nested'Unrestricted_Access; 11037 P1; 11038 end P2; 11039 11040end P; 11041@end example 11042 11043When P1 is called from P2, the call via Global is OK, but if P1 were 11044called after P2 returns, it would be an erroneous use of a dangling 11045pointer. 11046 11047For objects, it is possible to use @cite{Unrestricted_Access} for any 11048type. However, if the result is of an access-to-unconstrained array 11049subtype, then the resulting pointer has the same scope as the context 11050of the attribute, and must not be returned to some enclosing scope. 11051For instance, if a function uses @cite{Unrestricted_Access} to create 11052an access-to-unconstrained-array and returns that value to the caller, 11053the result will involve dangling pointers. In addition, it is only 11054valid to create pointers to unconstrained arrays using this attribute 11055if the pointer has the normal default 'fat' representation where a 11056pointer has two components, one points to the array and one points to 11057the bounds. If a size clause is used to force 'thin' representation 11058for a pointer to unconstrained where there is only space for a single 11059pointer, then the resulting pointer is not usable. 11060 11061In the simple case where a direct use of Unrestricted_Access attempts 11062to make a thin pointer for a non-aliased object, the compiler will 11063reject the use as illegal, as shown in the following example: 11064 11065@example 11066with System; use System; 11067procedure SliceUA2 is 11068 type A is access all String; 11069 for A'Size use Standard'Address_Size; 11070 11071 procedure P (Arg : A) is 11072 begin 11073 null; 11074 end P; 11075 11076 X : String := "hello world!"; 11077 X2 : aliased String := "hello world!"; 11078 11079 AV : A := X'Unrestricted_Access; -- ERROR 11080 | 11081>>> illegal use of Unrestricted_Access attribute 11082>>> attempt to generate thin pointer to unaliased object 11083 11084begin 11085 P (X'Unrestricted_Access); -- ERROR 11086 | 11087>>> illegal use of Unrestricted_Access attribute 11088>>> attempt to generate thin pointer to unaliased object 11089 11090 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11091 | 11092>>> illegal use of Unrestricted_Access attribute 11093>>> attempt to generate thin pointer to unaliased object 11094 11095 P (X2'Unrestricted_Access); -- OK 11096end; 11097@end example 11098 11099but other cases cannot be detected by the compiler, and are 11100considered to be erroneous. Consider the following example: 11101 11102@example 11103with System; use System; 11104with System; use System; 11105procedure SliceUA is 11106 type AF is access all String; 11107 11108 type A is access all String; 11109 for A'Size use Standard'Address_Size; 11110 11111 procedure P (Arg : A) is 11112 begin 11113 if Arg'Length /= 6 then 11114 raise Program_Error; 11115 end if; 11116 end P; 11117 11118 X : String := "hello world!"; 11119 Y : AF := X (7 .. 12)'Unrestricted_Access; 11120 11121begin 11122 P (A (Y)); 11123end; 11124@end example 11125 11126A normal unconstrained array value 11127or a constrained array object marked as aliased has the bounds in memory 11128just before the array, so a thin pointer can retrieve both the data and 11129the bounds. But in this case, the non-aliased object @cite{X} does not have the 11130bounds before the string. If the size clause for type @cite{A} 11131were not present, then the pointer 11132would be a fat pointer, where one component is a pointer to the bounds, 11133and all would be well. But with the size clause present, the conversion from 11134fat pointer to thin pointer in the call loses the bounds, and so this 11135is erroneous, and the program likely raises a @cite{Program_Error} exception. 11136 11137In general, it is advisable to completely 11138avoid mixing the use of thin pointers and the use of 11139@cite{Unrestricted_Access} where the designated type is an 11140unconstrained array. The use of thin pointers should be restricted to 11141cases of porting legacy code that implicitly assumes the size of pointers, 11142and such code should not in any case be using this attribute. 11143 11144Another erroneous situation arises if the attribute is 11145applied to a constant. The resulting pointer can be used to access the 11146constant, but the effect of trying to modify a constant in this manner 11147is not well-defined. Consider this example: 11148 11149@example 11150P : constant Integer := 4; 11151type R is access all Integer; 11152RV : R := P'Unrestricted_Access; 11153.. 11154RV.all := 3; 11155@end example 11156 11157Here we attempt to modify the constant P from 4 to 3, but the compiler may 11158or may not notice this attempt, and subsequent references to P may yield 11159either the value 3 or the value 4 or the assignment may blow up if the 11160compiler decides to put P in read-only memory. One particular case where 11161@cite{Unrestricted_Access} can be used in this way is to modify the 11162value of an @cite{IN} parameter: 11163 11164@example 11165procedure K (S : in String) is 11166 type R is access all Character; 11167 RV : R := S (3)'Unrestricted_Access; 11168begin 11169 RV.all := 'a'; 11170end; 11171@end example 11172 11173In general this is a risky approach. It may appear to "work" but such uses of 11174@cite{Unrestricted_Access} are potentially non-portable, even from one version 11175of @cite{GNAT} to another, so are best avoided if possible. 11176 11177@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes 11178@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{166} 11179@section Attribute Update 11180 11181 11182@geindex Update 11183 11184The @cite{Update} attribute creates a copy of an array or record value 11185with one or more modified components. The syntax is: 11186 11187@example 11188PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 11189PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 11190PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 11191 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 11192 11193MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 11194INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 11195INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 11196@end example 11197 11198where @cite{PREFIX} is the name of an array or record object, the 11199association list in parentheses does not contain an @cite{others} 11200choice and the box symbol @cite{<>} may not appear in any 11201expression. The effect is to yield a copy of the array or record value 11202which is unchanged apart from the components mentioned in the 11203association list, which are changed to the indicated value. The 11204original value of the array or record value is not affected. For 11205example: 11206 11207@example 11208type Arr is Array (1 .. 5) of Integer; 11209... 11210Avar1 : Arr := (1,2,3,4,5); 11211Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 11212@end example 11213 11214yields a value for @cite{Avar2} of 1,10,20,20,5 with @cite{Avar1} 11215begin unmodified. Similarly: 11216 11217@example 11218type Rec is A, B, C : Integer; 11219... 11220Rvar1 : Rec := (A => 1, B => 2, C => 3); 11221Rvar2 : Rec := Rvar1'Update (B => 20); 11222@end example 11223 11224yields a value for @cite{Rvar2} of (A => 1, B => 20, C => 3), 11225with @cite{Rvar1} being unmodifed. 11226Note that the value of the attribute reference is computed 11227completely before it is used. This means that if you write: 11228 11229@example 11230Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 11231@end example 11232 11233then the value of @cite{Avar1} is not modified if @cite{Function_Call} 11234raises an exception, unlike the effect of a series of direct assignments 11235to elements of @cite{Avar1}. In general this requires that 11236two extra complete copies of the object are required, which should be 11237kept in mind when considering efficiency. 11238 11239The @cite{Update} attribute cannot be applied to prefixes of a limited 11240type, and cannot reference discriminants in the case of a record type. 11241The accessibility level of an Update attribute result object is defined 11242as for an aggregate. 11243 11244In the record case, no component can be mentioned more than once. In 11245the array case, two overlapping ranges can appear in the association list, 11246in which case the modifications are processed left to right. 11247 11248Multi-dimensional arrays can be modified, as shown by this example: 11249 11250@example 11251A : array (1 .. 10, 1 .. 10) of Integer; 11252.. 11253A := A'Update ((1, 2) => 20, (3, 4) => 30); 11254@end example 11255 11256which changes element (1,2) to 20 and (3,4) to 30. 11257 11258@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes 11259@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{167} 11260@section Attribute Valid_Scalars 11261 11262 11263@geindex Valid_Scalars 11264 11265The @cite{'Valid_Scalars} attribute is intended to make it easier to 11266check the validity of scalar subcomponents of composite objects. It 11267is defined for any prefix @cite{X} that denotes an object. 11268The value of this attribute is of the predefined type Boolean. 11269@cite{X'Valid_Scalars} yields True if and only if evaluation of 11270@cite{P'Valid} yields True for every scalar part P of X or if X has 11271no scalar parts. It is not specified in what order the scalar parts 11272are checked, nor whether any more are checked after any one of them 11273is determined to be invalid. If the prefix @cite{X} is of a class-wide 11274type @cite{T'Class} (where @cite{T} is the associated specific type), 11275or if the prefix @cite{X} is of a specific tagged type @cite{T}, then 11276only the scalar parts of components of @cite{T} are traversed; in other 11277words, components of extensions of @cite{T} are not traversed even if 11278@cite{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can 11279be determined at compile time that the prefix of the attribute has no 11280scalar parts (e.g., if the prefix is of an access type, an interface type, 11281an undiscriminated task type, or an undiscriminated protected type). 11282 11283For scalar types, @cite{Valid_Scalars} is equivalent to @cite{Valid}. The use 11284of this attribute is not permitted for @cite{Unchecked_Union} types for which 11285in general it is not possible to determine the values of the discriminants. 11286 11287Note: @cite{Valid_Scalars} can generate a lot of code, especially in the case 11288of a large variant record. If the attribute is called in many places in the 11289same program applied to objects of the same type, it can reduce program size 11290to write a function with a single use of the attribute, and then call that 11291function from multiple places. 11292 11293@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 11294@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{168} 11295@section Attribute VADS_Size 11296 11297 11298@geindex Size 11299@geindex VADS compatibility 11300 11301@geindex VADS_Size 11302 11303The @cite{'VADS_Size} attribute is intended to make it easier to port 11304legacy code which relies on the semantics of @cite{'Size} as implemented 11305by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 11306same semantic interpretation. In particular, @cite{'VADS_Size} applied 11307to a predefined or other primitive type with no Size clause yields the 11308Object_Size (for example, @cite{Natural'Size} is 32 rather than 31 on 11309typical machines). In addition @cite{'VADS_Size} applied to an object 11310gives the result that would be obtained by applying the attribute to 11311the corresponding type. 11312 11313@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 11314@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{169} 11315@section Attribute Value_Size 11316 11317 11318@geindex Size 11319@geindex setting for not-first subtype 11320 11321@geindex Value_Size 11322 11323@code{type'Value_Size} is the number of bits required to represent 11324a value of the given subtype. It is the same as @code{type'Size}, 11325but, unlike @cite{Size}, may be set for non-first subtypes. 11326 11327@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 11328@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{16a} 11329@section Attribute Wchar_T_Size 11330 11331 11332@geindex Wchar_T_Size 11333 11334@cite{Standard'Wchar_T_Size} (@cite{Standard} is the only permissible 11335prefix) provides the size in bits of the C @cite{wchar_t} type 11336primarily for constructing the definition of this type in 11337package @cite{Interfaces.C}. The result is a static constant. 11338 11339@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 11340@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{16b} 11341@section Attribute Word_Size 11342 11343 11344@geindex Word_Size 11345 11346@cite{Standard'Word_Size} (@cite{Standard} is the only permissible 11347prefix) provides the value @cite{System.Word_Size}. The result is 11348a static constant. 11349 11350@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 11351@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{16c}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{16d} 11352@chapter Standard and Implementation Defined Restrictions 11353 11354 11355All Ada Reference Manual-defined Restriction identifiers are implemented: 11356 11357 11358@itemize * 11359 11360@item 11361language-defined restrictions (see 13.12.1) 11362 11363@item 11364tasking restrictions (see D.7) 11365 11366@item 11367high integrity restrictions (see H.4) 11368@end itemize 11369 11370GNAT implements additional restriction identifiers. All restrictions, whether 11371language defined or GNAT-specific, are listed in the following. 11372 11373@menu 11374* Partition-Wide Restrictions:: 11375* Program Unit Level Restrictions:: 11376 11377@end menu 11378 11379@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 11380@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{16e}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{16f} 11381@section Partition-Wide Restrictions 11382 11383 11384There are two separate lists of restriction identifiers. The first 11385set requires consistency throughout a partition (in other words, if the 11386restriction identifier is used for any compilation unit in the partition, 11387then all compilation units in the partition must obey the restriction). 11388 11389@menu 11390* Immediate_Reclamation:: 11391* Max_Asynchronous_Select_Nesting:: 11392* Max_Entry_Queue_Length:: 11393* Max_Protected_Entries:: 11394* Max_Select_Alternatives:: 11395* Max_Storage_At_Blocking:: 11396* Max_Task_Entries:: 11397* Max_Tasks:: 11398* No_Abort_Statements:: 11399* No_Access_Parameter_Allocators:: 11400* No_Access_Subprograms:: 11401* No_Allocators:: 11402* No_Anonymous_Allocators:: 11403* No_Asynchronous_Control:: 11404* No_Calendar:: 11405* No_Coextensions:: 11406* No_Default_Initialization:: 11407* No_Delay:: 11408* No_Dependence:: 11409* No_Direct_Boolean_Operators:: 11410* No_Dispatch:: 11411* No_Dispatching_Calls:: 11412* No_Dynamic_Attachment:: 11413* No_Dynamic_Priorities:: 11414* No_Entry_Calls_In_Elaboration_Code:: 11415* No_Enumeration_Maps:: 11416* No_Exception_Handlers:: 11417* No_Exception_Propagation:: 11418* No_Exception_Registration:: 11419* No_Exceptions:: 11420* No_Finalization:: 11421* No_Fixed_Point:: 11422* No_Floating_Point:: 11423* No_Implicit_Conditionals:: 11424* No_Implicit_Dynamic_Code:: 11425* No_Implicit_Heap_Allocations:: 11426* No_Implicit_Loops:: 11427* No_Implicit_Protected_Object_Allocations:: 11428* No_Implicit_Task_Allocations:: 11429* No_Initialize_Scalars:: 11430* No_IO:: 11431* No_Local_Allocators:: 11432* No_Local_Protected_Objects:: 11433* No_Local_Timing_Events:: 11434* No_Long_Long_Integers:: 11435* No_Multiple_Elaboration:: 11436* No_Nested_Finalization:: 11437* No_Protected_Type_Allocators:: 11438* No_Protected_Types:: 11439* No_Recursion:: 11440* No_Reentrancy:: 11441* No_Relative_Delay:: 11442* No_Requeue_Statements:: 11443* No_Secondary_Stack:: 11444* No_Select_Statements:: 11445* No_Specific_Termination_Handlers:: 11446* No_Specification_of_Aspect:: 11447* No_Standard_Allocators_After_Elaboration:: 11448* No_Standard_Storage_Pools:: 11449* No_Stream_Optimizations:: 11450* No_Streams:: 11451* No_Task_Allocators:: 11452* No_Task_At_Interrupt_Priority:: 11453* No_Task_Attributes_Package:: 11454* No_Task_Hierarchy:: 11455* No_Task_Termination:: 11456* No_Tasking:: 11457* No_Terminate_Alternatives:: 11458* No_Unchecked_Access:: 11459* No_Unchecked_Conversion:: 11460* No_Unchecked_Deallocation:: 11461* No_Use_Of_Entity:: 11462* Pure_Barriers:: 11463* Simple_Barriers:: 11464* Static_Priorities:: 11465* Static_Storage_Size:: 11466 11467@end menu 11468 11469@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 11470@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{170} 11471@subsection Immediate_Reclamation 11472 11473 11474@geindex Immediate_Reclamation 11475 11476[RM H.4] This restriction ensures that, except for storage occupied by 11477objects created by allocators and not deallocated via unchecked 11478deallocation, any storage reserved at run time for an object is 11479immediately reclaimed when the object no longer exists. 11480 11481@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 11482@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{171} 11483@subsection Max_Asynchronous_Select_Nesting 11484 11485 11486@geindex Max_Asynchronous_Select_Nesting 11487 11488[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 11489selects. Violations of this restriction with a value of zero are 11490detected at compile time. Violations of this restriction with values 11491other than zero cause Storage_Error to be raised. 11492 11493@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 11494@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{172} 11495@subsection Max_Entry_Queue_Length 11496 11497 11498@geindex Max_Entry_Queue_Length 11499 11500[RM D.7] This restriction is a declaration that any protected entry compiled in 11501the scope of the restriction has at most the specified number of 11502tasks waiting on the entry at any one time, and so no queue is required. 11503Note that this restriction is checked at run time. Violation of this 11504restriction results in the raising of Program_Error exception at the point of 11505the call. 11506 11507@geindex Max_Entry_Queue_Depth 11508 11509The restriction @cite{Max_Entry_Queue_Depth} is recognized as a 11510synonym for @cite{Max_Entry_Queue_Length}. This is retained for historical 11511compatibility purposes (and a warning will be generated for its use if 11512warnings on obsolescent features are activated). 11513 11514@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 11515@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{173} 11516@subsection Max_Protected_Entries 11517 11518 11519@geindex Max_Protected_Entries 11520 11521[RM D.7] Specifies the maximum number of entries per protected type. The 11522bounds of every entry family of a protected unit shall be static, or shall be 11523defined by a discriminant of a subtype whose corresponding bound is static. 11524 11525@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 11526@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{174} 11527@subsection Max_Select_Alternatives 11528 11529 11530@geindex Max_Select_Alternatives 11531 11532[RM D.7] Specifies the maximum number of alternatives in a selective accept. 11533 11534@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 11535@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{175} 11536@subsection Max_Storage_At_Blocking 11537 11538 11539@geindex Max_Storage_At_Blocking 11540 11541[RM D.7] Specifies the maximum portion (in storage elements) of a task's 11542Storage_Size that can be retained by a blocked task. A violation of this 11543restriction causes Storage_Error to be raised. 11544 11545@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 11546@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{176} 11547@subsection Max_Task_Entries 11548 11549 11550@geindex Max_Task_Entries 11551 11552[RM D.7] Specifies the maximum number of entries 11553per task. The bounds of every entry family 11554of a task unit shall be static, or shall be 11555defined by a discriminant of a subtype whose 11556corresponding bound is static. 11557 11558@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 11559@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{177} 11560@subsection Max_Tasks 11561 11562 11563@geindex Max_Tasks 11564 11565[RM D.7] Specifies the maximum number of task that may be created, not 11566counting the creation of the environment task. Violations of this 11567restriction with a value of zero are detected at compile 11568time. Violations of this restriction with values other than zero cause 11569Storage_Error to be raised. 11570 11571@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 11572@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{178} 11573@subsection No_Abort_Statements 11574 11575 11576@geindex No_Abort_Statements 11577 11578[RM D.7] There are no abort_statements, and there are 11579no calls to Task_Identification.Abort_Task. 11580 11581@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 11582@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{179} 11583@subsection No_Access_Parameter_Allocators 11584 11585 11586@geindex No_Access_Parameter_Allocators 11587 11588[RM H.4] This restriction ensures at compile time that there are no 11589occurrences of an allocator as the actual parameter to an access 11590parameter. 11591 11592@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 11593@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{17a} 11594@subsection No_Access_Subprograms 11595 11596 11597@geindex No_Access_Subprograms 11598 11599[RM H.4] This restriction ensures at compile time that there are no 11600declarations of access-to-subprogram types. 11601 11602@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 11603@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{17b} 11604@subsection No_Allocators 11605 11606 11607@geindex No_Allocators 11608 11609[RM H.4] This restriction ensures at compile time that there are no 11610occurrences of an allocator. 11611 11612@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 11613@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{17c} 11614@subsection No_Anonymous_Allocators 11615 11616 11617@geindex No_Anonymous_Allocators 11618 11619[RM H.4] This restriction ensures at compile time that there are no 11620occurrences of an allocator of anonymous access type. 11621 11622@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 11623@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{17d} 11624@subsection No_Asynchronous_Control 11625 11626 11627@geindex No_Asynchronous_Control 11628 11629[RM J.13] This restriction ensures at compile time that there are no semantic 11630dependences on the predefined package Asynchronous_Task_Control. 11631 11632@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 11633@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{17e} 11634@subsection No_Calendar 11635 11636 11637@geindex No_Calendar 11638 11639[GNAT] This restriction ensures at compile time that there are no semantic 11640dependences on package Calendar. 11641 11642@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 11643@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{17f} 11644@subsection No_Coextensions 11645 11646 11647@geindex No_Coextensions 11648 11649[RM H.4] This restriction ensures at compile time that there are no 11650coextensions. See 3.10.2. 11651 11652@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 11653@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{180} 11654@subsection No_Default_Initialization 11655 11656 11657@geindex No_Default_Initialization 11658 11659[GNAT] This restriction prohibits any instance of default initialization 11660of variables. The binder implements a consistency rule which prevents 11661any unit compiled without the restriction from with'ing a unit with the 11662restriction (this allows the generation of initialization procedures to 11663be skipped, since you can be sure that no call is ever generated to an 11664initialization procedure in a unit with the restriction active). If used 11665in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 11666is to prohibit all cases of variables declared without a specific 11667initializer (including the case of OUT scalar parameters). 11668 11669@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 11670@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{181} 11671@subsection No_Delay 11672 11673 11674@geindex No_Delay 11675 11676[RM H.4] This restriction ensures at compile time that there are no 11677delay statements and no semantic dependences on package Calendar. 11678 11679@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 11680@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{182} 11681@subsection No_Dependence 11682 11683 11684@geindex No_Dependence 11685 11686[RM 13.12.1] This restriction ensures at compile time that there are no 11687dependences on a library unit. 11688 11689@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 11690@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{183} 11691@subsection No_Direct_Boolean_Operators 11692 11693 11694@geindex No_Direct_Boolean_Operators 11695 11696[GNAT] This restriction ensures that no logical operators (and/or/xor) 11697are used on operands of type Boolean (or any type derived from Boolean). 11698This is intended for use in safety critical programs where the certification 11699protocol requires the use of short-circuit (and then, or else) forms for all 11700composite boolean operations. 11701 11702@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 11703@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{184} 11704@subsection No_Dispatch 11705 11706 11707@geindex No_Dispatch 11708 11709[RM H.4] This restriction ensures at compile time that there are no 11710occurrences of @cite{T'Class}, for any (tagged) subtype @cite{T}. 11711 11712@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 11713@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{185} 11714@subsection No_Dispatching_Calls 11715 11716 11717@geindex No_Dispatching_Calls 11718 11719[GNAT] This restriction ensures at compile time that the code generated by the 11720compiler involves no dispatching calls. The use of this restriction allows the 11721safe use of record extensions, classwide membership tests and other classwide 11722features not involving implicit dispatching. This restriction ensures that 11723the code contains no indirect calls through a dispatching mechanism. Note that 11724this includes internally-generated calls created by the compiler, for example 11725in the implementation of class-wide objects assignments. The 11726membership test is allowed in the presence of this restriction, because its 11727implementation requires no dispatching. 11728This restriction is comparable to the official Ada restriction 11729@cite{No_Dispatch} except that it is a bit less restrictive in that it allows 11730all classwide constructs that do not imply dispatching. 11731The following example indicates constructs that violate this restriction. 11732 11733@example 11734package Pkg is 11735 type T is tagged record 11736 Data : Natural; 11737 end record; 11738 procedure P (X : T); 11739 11740 type DT is new T with record 11741 More_Data : Natural; 11742 end record; 11743 procedure Q (X : DT); 11744end Pkg; 11745 11746with Pkg; use Pkg; 11747procedure Example is 11748 procedure Test (O : T'Class) is 11749 N : Natural := O'Size;-- Error: Dispatching call 11750 C : T'Class := O; -- Error: implicit Dispatching Call 11751 begin 11752 if O in DT'Class then -- OK : Membership test 11753 Q (DT (O)); -- OK : Type conversion plus direct call 11754 else 11755 P (O); -- Error: Dispatching call 11756 end if; 11757 end Test; 11758 11759 Obj : DT; 11760begin 11761 P (Obj); -- OK : Direct call 11762 P (T (Obj)); -- OK : Type conversion plus direct call 11763 P (T'Class (Obj)); -- Error: Dispatching call 11764 11765 Test (Obj); -- OK : Type conversion 11766 11767 if Obj in T'Class then -- OK : Membership test 11768 null; 11769 end if; 11770end Example; 11771@end example 11772 11773@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 11774@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{186} 11775@subsection No_Dynamic_Attachment 11776 11777 11778@geindex No_Dynamic_Attachment 11779 11780[RM D.7] This restriction ensures that there is no call to any of the 11781operations defined in package Ada.Interrupts 11782(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 11783Detach_Handler, and Reference). 11784 11785@geindex No_Dynamic_Interrupts 11786 11787The restriction @cite{No_Dynamic_Interrupts} is recognized as a 11788synonym for @cite{No_Dynamic_Attachment}. This is retained for historical 11789compatibility purposes (and a warning will be generated for its use if 11790warnings on obsolescent features are activated). 11791 11792@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 11793@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{187} 11794@subsection No_Dynamic_Priorities 11795 11796 11797@geindex No_Dynamic_Priorities 11798 11799[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 11800 11801@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 11802@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{188} 11803@subsection No_Entry_Calls_In_Elaboration_Code 11804 11805 11806@geindex No_Entry_Calls_In_Elaboration_Code 11807 11808[GNAT] This restriction ensures at compile time that no task or protected entry 11809calls are made during elaboration code. As a result of the use of this 11810restriction, the compiler can assume that no code past an accept statement 11811in a task can be executed at elaboration time. 11812 11813@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 11814@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{189} 11815@subsection No_Enumeration_Maps 11816 11817 11818@geindex No_Enumeration_Maps 11819 11820[GNAT] This restriction ensures at compile time that no operations requiring 11821enumeration maps are used (that is Image and Value attributes applied 11822to enumeration types). 11823 11824@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 11825@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{18a} 11826@subsection No_Exception_Handlers 11827 11828 11829@geindex No_Exception_Handlers 11830 11831[GNAT] This restriction ensures at compile time that there are no explicit 11832exception handlers. It also indicates that no exception propagation will 11833be provided. In this mode, exceptions may be raised but will result in 11834an immediate call to the last chance handler, a routine that the user 11835must define with the following profile: 11836 11837@example 11838procedure Last_Chance_Handler 11839 (Source_Location : System.Address; Line : Integer); 11840pragma Export (C, Last_Chance_Handler, 11841 "__gnat_last_chance_handler"); 11842@end example 11843 11844The parameter is a C null-terminated string representing a message to be 11845associated with the exception (typically the source location of the raise 11846statement generated by the compiler). The Line parameter when nonzero 11847represents the line number in the source program where the raise occurs. 11848 11849@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 11850@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{18b} 11851@subsection No_Exception_Propagation 11852 11853 11854@geindex No_Exception_Propagation 11855 11856[GNAT] This restriction guarantees that exceptions are never propagated 11857to an outer subprogram scope. The only case in which an exception may 11858be raised is when the handler is statically in the same subprogram, so 11859that the effect of a raise is essentially like a goto statement. Any 11860other raise statement (implicit or explicit) will be considered 11861unhandled. Exception handlers are allowed, but may not contain an 11862exception occurrence identifier (exception choice). In addition, use of 11863the package GNAT.Current_Exception is not permitted, and reraise 11864statements (raise with no operand) are not permitted. 11865 11866@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 11867@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{18c} 11868@subsection No_Exception_Registration 11869 11870 11871@geindex No_Exception_Registration 11872 11873[GNAT] This restriction ensures at compile time that no stream operations for 11874types Exception_Id or Exception_Occurrence are used. This also makes it 11875impossible to pass exceptions to or from a partition with this restriction 11876in a distributed environment. If this restriction is active, the generated 11877code is simplified by omitting the otherwise-required global registration 11878of exceptions when they are declared. 11879 11880@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 11881@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{18d} 11882@subsection No_Exceptions 11883 11884 11885@geindex No_Exceptions 11886 11887[RM H.4] This restriction ensures at compile time that there are no 11888raise statements and no exception handlers. 11889 11890@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 11891@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{18e} 11892@subsection No_Finalization 11893 11894 11895@geindex No_Finalization 11896 11897[GNAT] This restriction disables the language features described in 11898chapter 7.6 of the Ada 2005 RM as well as all form of code generation 11899performed by the compiler to support these features. The following types 11900are no longer considered controlled when this restriction is in effect: 11901 11902 11903@itemize * 11904 11905@item 11906@cite{Ada.Finalization.Controlled} 11907 11908@item 11909@cite{Ada.Finalization.Limited_Controlled} 11910 11911@item 11912Derivations from @cite{Controlled} or @cite{Limited_Controlled} 11913 11914@item 11915Class-wide types 11916 11917@item 11918Protected types 11919 11920@item 11921Task types 11922 11923@item 11924Array and record types with controlled components 11925@end itemize 11926 11927The compiler no longer generates code to initialize, finalize or adjust an 11928object or a nested component, either declared on the stack or on the heap. The 11929deallocation of a controlled object no longer finalizes its contents. 11930 11931@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 11932@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{18f} 11933@subsection No_Fixed_Point 11934 11935 11936@geindex No_Fixed_Point 11937 11938[RM H.4] This restriction ensures at compile time that there are no 11939occurrences of fixed point types and operations. 11940 11941@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 11942@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{190} 11943@subsection No_Floating_Point 11944 11945 11946@geindex No_Floating_Point 11947 11948[RM H.4] This restriction ensures at compile time that there are no 11949occurrences of floating point types and operations. 11950 11951@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 11952@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{191} 11953@subsection No_Implicit_Conditionals 11954 11955 11956@geindex No_Implicit_Conditionals 11957 11958[GNAT] This restriction ensures that the generated code does not contain any 11959implicit conditionals, either by modifying the generated code where possible, 11960or by rejecting any construct that would otherwise generate an implicit 11961conditional. Note that this check does not include run time constraint 11962checks, which on some targets may generate implicit conditionals as 11963well. To control the latter, constraint checks can be suppressed in the 11964normal manner. Constructs generating implicit conditionals include comparisons 11965of composite objects and the Max/Min attributes. 11966 11967@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 11968@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{192} 11969@subsection No_Implicit_Dynamic_Code 11970 11971 11972@geindex No_Implicit_Dynamic_Code 11973 11974@geindex trampoline 11975 11976[GNAT] This restriction prevents the compiler from building 'trampolines'. 11977This is a structure that is built on the stack and contains dynamic 11978code to be executed at run time. On some targets, a trampoline is 11979built for the following features: @cite{Access}, 11980@cite{Unrestricted_Access}, or @cite{Address} of a nested subprogram; 11981nested task bodies; primitive operations of nested tagged types. 11982Trampolines do not work on machines that prevent execution of stack 11983data. For example, on windows systems, enabling DEP (data execution 11984protection) will cause trampolines to raise an exception. 11985Trampolines are also quite slow at run time. 11986 11987On many targets, trampolines have been largely eliminated. Look at the 11988version of system.ads for your target --- if it has 11989Always_Compatible_Rep equal to False, then trampolines are largely 11990eliminated. In particular, a trampoline is built for the following 11991features: @cite{Address} of a nested subprogram; 11992@cite{Access} or @cite{Unrestricted_Access} of a nested subprogram, 11993but only if pragma Favor_Top_Level applies, or the access type has a 11994foreign-language convention; primitive operations of nested tagged 11995types. 11996 11997@node No_Implicit_Heap_Allocations,No_Implicit_Loops,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 11998@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{193} 11999@subsection No_Implicit_Heap_Allocations 12000 12001 12002@geindex No_Implicit_Heap_Allocations 12003 12004[RM D.7] No constructs are allowed to cause implicit heap allocation. 12005 12006@node No_Implicit_Loops,No_Implicit_Protected_Object_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12007@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{194} 12008@subsection No_Implicit_Loops 12009 12010 12011@geindex No_Implicit_Loops 12012 12013[GNAT] This restriction ensures that the generated code does not contain any 12014implicit @cite{for} loops, either by modifying 12015the generated code where possible, 12016or by rejecting any construct that would otherwise generate an implicit 12017@cite{for} loop. If this restriction is active, it is possible to build 12018large array aggregates with all static components without generating an 12019intermediate temporary, and without generating a loop to initialize individual 12020components. Otherwise, a loop is created for arrays larger than about 5000 12021scalar components. 12022 12023@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Loops,Partition-Wide Restrictions 12024@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{195} 12025@subsection No_Implicit_Protected_Object_Allocations 12026 12027 12028@geindex No_Implicit_Protected_Object_Allocations 12029 12030[GNAT] No constructs are allowed to cause implicit heap allocation of a 12031protected object. 12032 12033@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12034@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{196} 12035@subsection No_Implicit_Task_Allocations 12036 12037 12038@geindex No_Implicit_Task_Allocations 12039 12040[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12041 12042@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12043@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{197} 12044@subsection No_Initialize_Scalars 12045 12046 12047@geindex No_Initialize_Scalars 12048 12049[GNAT] This restriction ensures that no unit in the partition is compiled with 12050pragma Initialize_Scalars. This allows the generation of more efficient 12051code, and in particular eliminates dummy null initialization routines that 12052are otherwise generated for some record and array types. 12053 12054@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12055@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{198} 12056@subsection No_IO 12057 12058 12059@geindex No_IO 12060 12061[RM H.4] This restriction ensures at compile time that there are no 12062dependences on any of the library units Sequential_IO, Direct_IO, 12063Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12064 12065@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12066@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{199} 12067@subsection No_Local_Allocators 12068 12069 12070@geindex No_Local_Allocators 12071 12072[RM H.4] This restriction ensures at compile time that there are no 12073occurrences of an allocator in subprograms, generic subprograms, tasks, 12074and entry bodies. 12075 12076@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12077@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{19a} 12078@subsection No_Local_Protected_Objects 12079 12080 12081@geindex No_Local_Protected_Objects 12082 12083[RM D.7] This restriction ensures at compile time that protected objects are 12084only declared at the library level. 12085 12086@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12087@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{19b} 12088@subsection No_Local_Timing_Events 12089 12090 12091@geindex No_Local_Timing_Events 12092 12093[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 12094declared at the library level. 12095 12096@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12097@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{19c} 12098@subsection No_Long_Long_Integers 12099 12100 12101@geindex No_Long_Long_Integers 12102 12103[GNAT] This partition-wide restriction forbids any explicit reference to 12104type Standard.Long_Long_Integer, and also forbids declaring range types whose 12105implicit base type is Long_Long_Integer, and modular types whose size exceeds 12106Long_Integer'Size. 12107 12108@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12109@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{19d} 12110@subsection No_Multiple_Elaboration 12111 12112 12113@geindex No_Multiple_Elaboration 12114 12115[GNAT] Normally each package contains a 16-bit counter used to check for access 12116before elaboration, and to control multiple elaboration attempts. 12117This counter is eliminated for units compiled with the static model 12118of elaboration if restriction @cite{No_Elaboration_Code} 12119is active but because of 12120the need to check for multiple elaboration in the general case, these 12121counters cannot be eliminated if elaboration code may be present. The 12122restriction @cite{No_Multiple_Elaboration} 12123allows suppression of these counters 12124in static elaboration units even if they do have elaboration code. If this 12125restriction is used, then the situations in which multiple elaboration is 12126possible, including non-Ada main programs, and Stand Alone libraries, are not 12127permitted, and will be diagnosed by the binder. 12128 12129@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12130@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{19e} 12131@subsection No_Nested_Finalization 12132 12133 12134@geindex No_Nested_Finalization 12135 12136[RM D.7] All objects requiring finalization are declared at the library level. 12137 12138@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12139@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{19f} 12140@subsection No_Protected_Type_Allocators 12141 12142 12143@geindex No_Protected_Type_Allocators 12144 12145[RM D.7] This restriction ensures at compile time that there are no allocator 12146expressions that attempt to allocate protected objects. 12147 12148@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 12149@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1a0} 12150@subsection No_Protected_Types 12151 12152 12153@geindex No_Protected_Types 12154 12155[RM H.4] This restriction ensures at compile time that there are no 12156declarations of protected types or protected objects. 12157 12158@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 12159@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1a1} 12160@subsection No_Recursion 12161 12162 12163@geindex No_Recursion 12164 12165[RM H.4] A program execution is erroneous if a subprogram is invoked as 12166part of its execution. 12167 12168@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 12169@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1a2} 12170@subsection No_Reentrancy 12171 12172 12173@geindex No_Reentrancy 12174 12175[RM H.4] A program execution is erroneous if a subprogram is executed by 12176two tasks at the same time. 12177 12178@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 12179@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1a3} 12180@subsection No_Relative_Delay 12181 12182 12183@geindex No_Relative_Delay 12184 12185[RM D.7] This restriction ensures at compile time that there are no delay 12186relative statements and prevents expressions such as @cite{delay 1.23;} from 12187appearing in source code. 12188 12189@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 12190@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1a4} 12191@subsection No_Requeue_Statements 12192 12193 12194@geindex No_Requeue_Statements 12195 12196[RM D.7] This restriction ensures at compile time that no requeue statements 12197are permitted and prevents keyword @cite{requeue} from being used in source 12198code. 12199 12200@geindex No_Requeue 12201 12202The restriction @cite{No_Requeue} is recognized as a 12203synonym for @cite{No_Requeue_Statements}. This is retained for historical 12204compatibility purposes (and a warning will be generated for its use if 12205warnings on oNobsolescent features are activated). 12206 12207@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 12208@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1a5} 12209@subsection No_Secondary_Stack 12210 12211 12212@geindex No_Secondary_Stack 12213 12214[GNAT] This restriction ensures at compile time that the generated code 12215does not contain any reference to the secondary stack. The secondary 12216stack is used to implement functions returning unconstrained objects 12217(arrays or records) on some targets. 12218 12219@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 12220@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1a6} 12221@subsection No_Select_Statements 12222 12223 12224@geindex No_Select_Statements 12225 12226[RM D.7] This restriction ensures at compile time no select statements of any 12227kind are permitted, that is the keyword @cite{select} may not appear. 12228 12229@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 12230@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1a7} 12231@subsection No_Specific_Termination_Handlers 12232 12233 12234@geindex No_Specific_Termination_Handlers 12235 12236[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 12237or to Ada.Task_Termination.Specific_Handler. 12238 12239@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 12240@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1a8} 12241@subsection No_Specification_of_Aspect 12242 12243 12244@geindex No_Specification_of_Aspect 12245 12246[RM 13.12.1] This restriction checks at compile time that no aspect 12247specification, attribute definition clause, or pragma is given for a 12248given aspect. 12249 12250@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 12251@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1a9} 12252@subsection No_Standard_Allocators_After_Elaboration 12253 12254 12255@geindex No_Standard_Allocators_After_Elaboration 12256 12257[RM D.7] Specifies that an allocator using a standard storage pool 12258should never be evaluated at run time after the elaboration of the 12259library items of the partition has completed. Otherwise, Storage_Error 12260is raised. 12261 12262@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 12263@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1aa} 12264@subsection No_Standard_Storage_Pools 12265 12266 12267@geindex No_Standard_Storage_Pools 12268 12269[GNAT] This restriction ensures at compile time that no access types 12270use the standard default storage pool. Any access type declared must 12271have an explicit Storage_Pool attribute defined specifying a 12272user-defined storage pool. 12273 12274@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 12275@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1ab} 12276@subsection No_Stream_Optimizations 12277 12278 12279@geindex No_Stream_Optimizations 12280 12281[GNAT] This restriction affects the performance of stream operations on types 12282@cite{String}, @cite{Wide_String} and @cite{Wide_Wide_String}. By default, the 12283compiler uses block reads and writes when manipulating @cite{String} objects 12284due to their supperior performance. When this restriction is in effect, the 12285compiler performs all IO operations on a per-character basis. 12286 12287@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 12288@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1ac} 12289@subsection No_Streams 12290 12291 12292@geindex No_Streams 12293 12294[GNAT] This restriction ensures at compile/bind time that there are no 12295stream objects created and no use of stream attributes. 12296This restriction does not forbid dependences on the package 12297@cite{Ada.Streams}. So it is permissible to with 12298@cite{Ada.Streams} (or another package that does so itself) 12299as long as no actual stream objects are created and no 12300stream attributes are used. 12301 12302Note that the use of restriction allows optimization of tagged types, 12303since they do not need to worry about dispatching stream operations. 12304To take maximum advantage of this space-saving optimization, any 12305unit declaring a tagged type should be compiled with the restriction, 12306though this is not required. 12307 12308@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 12309@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1ad} 12310@subsection No_Task_Allocators 12311 12312 12313@geindex No_Task_Allocators 12314 12315[RM D.7] There are no allocators for task types 12316or types containing task subcomponents. 12317 12318@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 12319@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1ae} 12320@subsection No_Task_At_Interrupt_Priority 12321 12322 12323@geindex No_Task_At_Interrupt_Priority 12324 12325[GNAT] This restriction ensures at compile time that there is no 12326Interrupt_Priority aspect or pragma for a task or a task type. As 12327a consequence, the tasks are always created with a priority below 12328that an interrupt priority. 12329 12330@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 12331@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1af} 12332@subsection No_Task_Attributes_Package 12333 12334 12335@geindex No_Task_Attributes_Package 12336 12337[GNAT] This restriction ensures at compile time that there are no implicit or 12338explicit dependencies on the package @cite{Ada.Task_Attributes}. 12339 12340@geindex No_Task_Attributes 12341 12342The restriction @cite{No_Task_Attributes} is recognized as a synonym 12343for @cite{No_Task_Attributes_Package}. This is retained for historical 12344compatibility purposes (and a warning will be generated for its use if 12345warnings on obsolescent features are activated). 12346 12347@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 12348@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1b0} 12349@subsection No_Task_Hierarchy 12350 12351 12352@geindex No_Task_Hierarchy 12353 12354[RM D.7] All (non-environment) tasks depend 12355directly on the environment task of the partition. 12356 12357@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 12358@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1b1} 12359@subsection No_Task_Termination 12360 12361 12362@geindex No_Task_Termination 12363 12364[RM D.7] Tasks that terminate are erroneous. 12365 12366@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 12367@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1b2} 12368@subsection No_Tasking 12369 12370 12371@geindex No_Tasking 12372 12373[GNAT] This restriction prevents the declaration of tasks or task types 12374throughout the partition. It is similar in effect to the use of 12375@cite{Max_Tasks => 0} except that violations are caught at compile time 12376and cause an error message to be output either by the compiler or 12377binder. 12378 12379@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 12380@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1b3} 12381@subsection No_Terminate_Alternatives 12382 12383 12384@geindex No_Terminate_Alternatives 12385 12386[RM D.7] There are no selective accepts with terminate alternatives. 12387 12388@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 12389@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1b4} 12390@subsection No_Unchecked_Access 12391 12392 12393@geindex No_Unchecked_Access 12394 12395[RM H.4] This restriction ensures at compile time that there are no 12396occurrences of the Unchecked_Access attribute. 12397 12398@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 12399@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1b5} 12400@subsection No_Unchecked_Conversion 12401 12402 12403@geindex No_Unchecked_Conversion 12404 12405[RM J.13] This restriction ensures at compile time that there are no semantic 12406dependences on the predefined generic function Unchecked_Conversion. 12407 12408@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 12409@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1b6} 12410@subsection No_Unchecked_Deallocation 12411 12412 12413@geindex No_Unchecked_Deallocation 12414 12415[RM J.13] This restriction ensures at compile time that there are no semantic 12416dependences on the predefined generic procedure Unchecked_Deallocation. 12417 12418@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 12419@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1b7} 12420@subsection No_Use_Of_Entity 12421 12422 12423@geindex No_Use_Of_Entity 12424 12425[GNAT] This restriction ensures at compile time that there are no references 12426to the entity given in the form 12427 12428@example 12429No_Use_Of_Entity => Name 12430@end example 12431 12432where @code{Name} is the fully qualified entity, for example 12433 12434@example 12435No_Use_Of_Entity => Ada.Text_IO.Put_Line 12436@end example 12437 12438@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 12439@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1b8} 12440@subsection Pure_Barriers 12441 12442 12443@geindex Pure_Barriers 12444 12445[GNAT] This restriction ensures at compile time that protected entry 12446barriers are restricted to: 12447 12448 12449@itemize * 12450 12451@item 12452simple variables defined in the private part of the 12453protected type/object, 12454 12455@item 12456constant declarations, 12457 12458@item 12459named numbers, 12460 12461@item 12462enumeration literals, 12463 12464@item 12465integer literals, 12466 12467@item 12468real literals, 12469 12470@item 12471character literals, 12472 12473@item 12474implicitly defined comparison operators, 12475 12476@item 12477uses of the Standard."not" operator, 12478 12479@item 12480short-circuit operator 12481@end itemize 12482 12483This restriction is a relaxation of the Simple_Barriers restriction, 12484but still ensures absence of side effects, exceptions, and recursion 12485during the evaluation of the barriers. 12486 12487@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 12488@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{1b9} 12489@subsection Simple_Barriers 12490 12491 12492@geindex Simple_Barriers 12493 12494[RM D.7] This restriction ensures at compile time that barriers in entry 12495declarations for protected types are restricted to either static boolean 12496expressions or references to simple boolean variables defined in the private 12497part of the protected type. No other form of entry barriers is permitted. 12498 12499@geindex Boolean_Entry_Barriers 12500 12501The restriction @cite{Boolean_Entry_Barriers} is recognized as a 12502synonym for @cite{Simple_Barriers}. This is retained for historical 12503compatibility purposes (and a warning will be generated for its use if 12504warnings on obsolescent features are activated). 12505 12506@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 12507@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{1ba} 12508@subsection Static_Priorities 12509 12510 12511@geindex Static_Priorities 12512 12513[GNAT] This restriction ensures at compile time that all priority expressions 12514are static, and that there are no dependences on the package 12515@cite{Ada.Dynamic_Priorities}. 12516 12517@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 12518@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{1bb} 12519@subsection Static_Storage_Size 12520 12521 12522@geindex Static_Storage_Size 12523 12524[GNAT] This restriction ensures at compile time that any expression appearing 12525in a Storage_Size pragma or attribute definition clause is static. 12526 12527@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 12528@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{1bc}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{1bd} 12529@section Program Unit Level Restrictions 12530 12531 12532The second set of restriction identifiers 12533does not require partition-wide consistency. 12534The restriction may be enforced for a single 12535compilation unit without any effect on any of the 12536other compilation units in the partition. 12537 12538@menu 12539* No_Elaboration_Code:: 12540* No_Dynamic_Sized_Objects:: 12541* No_Entry_Queue:: 12542* No_Implementation_Aspect_Specifications:: 12543* No_Implementation_Attributes:: 12544* No_Implementation_Identifiers:: 12545* No_Implementation_Pragmas:: 12546* No_Implementation_Restrictions:: 12547* No_Implementation_Units:: 12548* No_Implicit_Aliasing:: 12549* No_Obsolescent_Features:: 12550* No_Wide_Characters:: 12551* SPARK_05:: 12552 12553@end menu 12554 12555@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions 12556@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{1be} 12557@subsection No_Elaboration_Code 12558 12559 12560@geindex No_Elaboration_Code 12561 12562[GNAT] This restriction ensures at compile time that no elaboration code is 12563generated. Note that this is not the same condition as is enforced 12564by pragma @cite{Preelaborate}. There are cases in which pragma 12565@cite{Preelaborate} still permits code to be generated (e.g., code 12566to initialize a large array to all zeroes), and there are cases of units 12567which do not meet the requirements for pragma @cite{Preelaborate}, 12568but for which no elaboration code is generated. Generally, it is 12569the case that preelaborable units will meet the restrictions, with 12570the exception of large aggregates initialized with an others_clause, 12571and exception declarations (which generate calls to a run-time 12572registry procedure). This restriction is enforced on 12573a unit by unit basis, it need not be obeyed consistently 12574throughout a partition. 12575 12576In the case of aggregates with others, if the aggregate has a dynamic 12577size, there is no way to eliminate the elaboration code (such dynamic 12578bounds would be incompatible with @cite{Preelaborate} in any case). If 12579the bounds are static, then use of this restriction actually modifies 12580the code choice of the compiler to avoid generating a loop, and instead 12581generate the aggregate statically if possible, no matter how many times 12582the data for the others clause must be repeatedly generated. 12583 12584It is not possible to precisely document 12585the constructs which are compatible with this restriction, since, 12586unlike most other restrictions, this is not a restriction on the 12587source code, but a restriction on the generated object code. For 12588example, if the source contains a declaration: 12589 12590@example 12591Val : constant Integer := X; 12592@end example 12593 12594where X is not a static constant, it may be possible, depending 12595on complex optimization circuitry, for the compiler to figure 12596out the value of X at compile time, in which case this initialization 12597can be done by the loader, and requires no initialization code. It 12598is not possible to document the precise conditions under which the 12599optimizer can figure this out. 12600 12601Note that this the implementation of this restriction requires full 12602code generation. If it is used in conjunction with "semantics only" 12603checking, then some cases of violations may be missed. 12604 12605@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions 12606@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{1bf} 12607@subsection No_Dynamic_Sized_Objects 12608 12609 12610@geindex No_Dynamic_Sized_Objects 12611 12612[GNAT] This restriction disallows certain constructs that might lead to the 12613creation of dynamic-sized composite objects (or array or discriminated type). 12614An array subtype indication is illegal if the bounds are not static 12615or references to discriminants of an enclosing type. 12616A discriminated subtype indication is illegal if the type has 12617discriminant-dependent array components or a variant part, and the 12618discriminants are not static. In addition, array and record aggregates are 12619illegal in corresponding cases. Note that this restriction does not forbid 12620access discriminants. It is often a good idea to combine this restriction 12621with No_Secondary_Stack. 12622 12623@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 12624@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{1c0} 12625@subsection No_Entry_Queue 12626 12627 12628@geindex No_Entry_Queue 12629 12630[GNAT] This restriction is a declaration that any protected entry compiled in 12631the scope of the restriction has at most one task waiting on the entry 12632at any one time, and so no queue is required. This restriction is not 12633checked at compile time. A program execution is erroneous if an attempt 12634is made to queue a second task on such an entry. 12635 12636@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 12637@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{1c1} 12638@subsection No_Implementation_Aspect_Specifications 12639 12640 12641@geindex No_Implementation_Aspect_Specifications 12642 12643[RM 13.12.1] This restriction checks at compile time that no 12644GNAT-defined aspects are present. With this restriction, the only 12645aspects that can be used are those defined in the Ada Reference Manual. 12646 12647@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 12648@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{1c2} 12649@subsection No_Implementation_Attributes 12650 12651 12652@geindex No_Implementation_Attributes 12653 12654[RM 13.12.1] This restriction checks at compile time that no 12655GNAT-defined attributes are present. With this restriction, the only 12656attributes that can be used are those defined in the Ada Reference 12657Manual. 12658 12659@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 12660@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{1c3} 12661@subsection No_Implementation_Identifiers 12662 12663 12664@geindex No_Implementation_Identifiers 12665 12666[RM 13.12.1] This restriction checks at compile time that no 12667implementation-defined identifiers (marked with pragma Implementation_Defined) 12668occur within language-defined packages. 12669 12670@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 12671@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{1c4} 12672@subsection No_Implementation_Pragmas 12673 12674 12675@geindex No_Implementation_Pragmas 12676 12677[RM 13.12.1] This restriction checks at compile time that no 12678GNAT-defined pragmas are present. With this restriction, the only 12679pragmas that can be used are those defined in the Ada Reference Manual. 12680 12681@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 12682@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{1c5} 12683@subsection No_Implementation_Restrictions 12684 12685 12686@geindex No_Implementation_Restrictions 12687 12688[GNAT] This restriction checks at compile time that no GNAT-defined restriction 12689identifiers (other than @cite{No_Implementation_Restrictions} itself) 12690are present. With this restriction, the only other restriction identifiers 12691that can be used are those defined in the Ada Reference Manual. 12692 12693@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 12694@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{1c6} 12695@subsection No_Implementation_Units 12696 12697 12698@geindex No_Implementation_Units 12699 12700[RM 13.12.1] This restriction checks at compile time that there is no 12701mention in the context clause of any implementation-defined descendants 12702of packages Ada, Interfaces, or System. 12703 12704@node No_Implicit_Aliasing,No_Obsolescent_Features,No_Implementation_Units,Program Unit Level Restrictions 12705@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{1c7} 12706@subsection No_Implicit_Aliasing 12707 12708 12709@geindex No_Implicit_Aliasing 12710 12711[GNAT] This restriction, which is not required to be partition-wide consistent, 12712requires an explicit aliased keyword for an object to which 'Access, 12713'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 12714the 'Unrestricted_Access attribute for objects. Note: the reason that 12715Unrestricted_Access is forbidden is that it would require the prefix 12716to be aliased, and in such cases, it can always be replaced by 12717the standard attribute Unchecked_Access which is preferable. 12718 12719@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Aliasing,Program Unit Level Restrictions 12720@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{1c8} 12721@subsection No_Obsolescent_Features 12722 12723 12724@geindex No_Obsolescent_Features 12725 12726[RM 13.12.1] This restriction checks at compile time that no obsolescent 12727features are used, as defined in Annex J of the Ada Reference Manual. 12728 12729@node No_Wide_Characters,SPARK_05,No_Obsolescent_Features,Program Unit Level Restrictions 12730@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{1c9} 12731@subsection No_Wide_Characters 12732 12733 12734@geindex No_Wide_Characters 12735 12736[GNAT] This restriction ensures at compile time that no uses of the types 12737@cite{Wide_Character} or @cite{Wide_String} or corresponding wide 12738wide types 12739appear, and that no wide or wide wide string or character literals 12740appear in the program (that is literals representing characters not in 12741type @cite{Character}). 12742 12743@node SPARK_05,,No_Wide_Characters,Program Unit Level Restrictions 12744@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{1ca} 12745@subsection SPARK_05 12746 12747 12748@geindex SPARK_05 12749 12750[GNAT] This restriction checks at compile time that some constructs 12751forbidden in SPARK 2005 are not present. Error messages related to 12752SPARK restriction have the form: 12753 12754@example 12755violation of restriction "SPARK_05" at <source-location> 12756 <error message> 12757@end example 12758 12759@geindex SPARK 12760 12761The restriction @cite{SPARK} is recognized as a 12762synonym for @cite{SPARK_05}. This is retained for historical 12763compatibility purposes (and an unconditional warning will be generated 12764for its use, advising replacement by @cite{SPARK}). 12765 12766This is not a replacement for the semantic checks performed by the 12767SPARK Examiner tool, as the compiler currently only deals with code, 12768not SPARK 2005 annotations, and does not guarantee catching all 12769cases of constructs forbidden by SPARK 2005. 12770 12771Thus it may well be the case that code which passes the compiler with 12772the SPARK restriction is rejected by the SPARK Examiner, e.g. due to 12773the different visibility rules of the Examiner based on SPARK 2005 12774@cite{inherit} annotations. 12775 12776This restriction can be useful in providing an initial filter for code 12777developed using SPARK 2005, or in examining legacy code to see how far 12778it is from meeting SPARK restrictions. 12779 12780The list below summarizes the checks that are performed when this 12781restriction is in force: 12782 12783 12784@itemize * 12785 12786@item 12787No block statements 12788 12789@item 12790No case statements with only an others clause 12791 12792@item 12793Exit statements in loops must respect the SPARK 2005 language restrictions 12794 12795@item 12796No goto statements 12797 12798@item 12799Return can only appear as last statement in function 12800 12801@item 12802Function must have return statement 12803 12804@item 12805Loop parameter specification must include subtype mark 12806 12807@item 12808Prefix of expanded name cannot be a loop statement 12809 12810@item 12811Abstract subprogram not allowed 12812 12813@item 12814User-defined operators not allowed 12815 12816@item 12817Access type parameters not allowed 12818 12819@item 12820Default expressions for parameters not allowed 12821 12822@item 12823Default expressions for record fields not allowed 12824 12825@item 12826No tasking constructs allowed 12827 12828@item 12829Label needed at end of subprograms and packages 12830 12831@item 12832No mixing of positional and named parameter association 12833 12834@item 12835No access types as result type 12836 12837@item 12838No unconstrained arrays as result types 12839 12840@item 12841No null procedures 12842 12843@item 12844Initial and later declarations must be in correct order (declaration can't come after body) 12845 12846@item 12847No attributes on private types if full declaration not visible 12848 12849@item 12850No package declaration within package specification 12851 12852@item 12853No controlled types 12854 12855@item 12856No discriminant types 12857 12858@item 12859No overloading 12860 12861@item 12862Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed) 12863 12864@item 12865Access attribute not allowed 12866 12867@item 12868Allocator not allowed 12869 12870@item 12871Result of catenation must be String 12872 12873@item 12874Operands of catenation must be string literal, static char or another catenation 12875 12876@item 12877No conditional expressions 12878 12879@item 12880No explicit dereference 12881 12882@item 12883Quantified expression not allowed 12884 12885@item 12886Slicing not allowed 12887 12888@item 12889No exception renaming 12890 12891@item 12892No generic renaming 12893 12894@item 12895No object renaming 12896 12897@item 12898No use clause 12899 12900@item 12901Aggregates must be qualified 12902 12903@item 12904Nonstatic choice in array aggregates not allowed 12905 12906@item 12907The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type 12908 12909@item 12910No mixing of positional and named association in aggregate, no multi choice 12911 12912@item 12913AND, OR and XOR for arrays only allowed when operands have same static bounds 12914 12915@item 12916Fixed point operands to * or / must be qualified or converted 12917 12918@item 12919Comparison operators not allowed for Booleans or arrays (except strings) 12920 12921@item 12922Equality not allowed for arrays with non-matching static bounds (except strings) 12923 12924@item 12925Conversion / qualification not allowed for arrays with non-matching static bounds 12926 12927@item 12928Subprogram declaration only allowed in package spec (unless followed by import) 12929 12930@item 12931Access types not allowed 12932 12933@item 12934Incomplete type declaration not allowed 12935 12936@item 12937Object and subtype declarations must respect SPARK restrictions 12938 12939@item 12940Digits or delta constraint not allowed 12941 12942@item 12943Decimal fixed point type not allowed 12944 12945@item 12946Aliasing of objects not allowed 12947 12948@item 12949Modular type modulus must be power of 2 12950 12951@item 12952Base not allowed on subtype mark 12953 12954@item 12955Unary operators not allowed on modular types (except not) 12956 12957@item 12958Untagged record cannot be null 12959 12960@item 12961No class-wide operations 12962 12963@item 12964Initialization expressions must respect SPARK restrictions 12965 12966@item 12967Nonstatic ranges not allowed except in iteration schemes 12968 12969@item 12970String subtypes must have lower bound of 1 12971 12972@item 12973Subtype of Boolean cannot have constraint 12974 12975@item 12976At most one tagged type or extension per package 12977 12978@item 12979Interface is not allowed 12980 12981@item 12982Character literal cannot be prefixed (selector name cannot be character literal) 12983 12984@item 12985Record aggregate cannot contain 'others' 12986 12987@item 12988Component association in record aggregate must contain a single choice 12989 12990@item 12991Ancestor part cannot be a type mark 12992 12993@item 12994Attributes 'Image, 'Width and 'Value not allowed 12995 12996@item 12997Functions may not update globals 12998 12999@item 13000Subprograms may not contain direct calls to themselves (prevents recursion within unit) 13001 13002@item 13003Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit) 13004@end itemize 13005 13006The following restrictions are enforced, but note that they are actually more 13007strict that the latest SPARK 2005 language definition: 13008 13009 13010@itemize * 13011 13012@item 13013No derived types other than tagged type extensions 13014 13015@item 13016Subtype of unconstrained array must have constraint 13017@end itemize 13018 13019This list summarises the main SPARK 2005 language rules that are not 13020currently checked by the SPARK_05 restriction: 13021 13022 13023@itemize * 13024 13025@item 13026SPARK annotations are treated as comments so are not checked at all 13027 13028@item 13029Based real literals not allowed 13030 13031@item 13032Objects cannot be initialized at declaration by calls to user-defined functions 13033 13034@item 13035Objects cannot be initialized at declaration by assignments from variables 13036 13037@item 13038Objects cannot be initialized at declaration by assignments from indexed/selected components 13039 13040@item 13041Ranges shall not be null 13042 13043@item 13044A fixed point delta expression must be a simple expression 13045 13046@item 13047Restrictions on where renaming declarations may be placed 13048 13049@item 13050Externals of mode 'out' cannot be referenced 13051 13052@item 13053Externals of mode 'in' cannot be updated 13054 13055@item 13056Loop with no iteration scheme or exits only allowed as last statement in main program or task 13057 13058@item 13059Subprogram cannot have parent unit name 13060 13061@item 13062SPARK 2005 inherited subprogram must be prefixed with overriding 13063 13064@item 13065External variables (or functions that reference them) may not be passed as actual parameters 13066 13067@item 13068Globals must be explicitly mentioned in contract 13069 13070@item 13071Deferred constants cannot be completed by pragma Import 13072 13073@item 13074Package initialization cannot read/write variables from other packages 13075 13076@item 13077Prefix not allowed for entities that are directly visible 13078 13079@item 13080Identifier declaration can't override inherited package name 13081 13082@item 13083Cannot use Standard or other predefined packages as identifiers 13084 13085@item 13086After renaming, cannot use the original name 13087 13088@item 13089Subprograms can only be renamed to remove package prefix 13090 13091@item 13092Pragma import must be immediately after entity it names 13093 13094@item 13095No mutual recursion between multiple units (this can be checked with gnatcheck) 13096@end itemize 13097 13098Note that if a unit is compiled in Ada 95 mode with the SPARK restriction, 13099violations will be reported for constructs forbidden in SPARK 95, 13100instead of SPARK 2005. 13101 13102@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13103@anchor{gnat_rm/implementation_advice doc}@anchor{1cb}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{1cc} 13104@chapter Implementation Advice 13105 13106 13107The main text of the Ada Reference Manual describes the required 13108behavior of all Ada compilers, and the GNAT compiler conforms to 13109these requirements. 13110 13111In addition, there are sections throughout the Ada Reference Manual headed 13112by the phrase 'Implementation advice'. These sections are not normative, 13113i.e., they do not specify requirements that all compilers must 13114follow. Rather they provide advice on generally desirable behavior. 13115They are not requirements, because they describe behavior that cannot 13116be provided on all systems, or may be undesirable on some systems. 13117 13118As far as practical, GNAT follows the implementation advice in 13119the Ada Reference Manual. Each such RM section corresponds to a section 13120in this chapter whose title specifies the 13121RM section number and paragraph number and the subject of 13122the advice. The contents of each section consists of the RM text within 13123quotation marks, 13124followed by the GNAT interpretation of the advice. Most often, this simply says 13125'followed', which means that GNAT follows the advice. However, in a 13126number of cases, GNAT deliberately deviates from this advice, in which 13127case the text describes what GNAT does and why. 13128 13129@geindex Error detection 13130 13131@menu 13132* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13133* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13134* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13135* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13136* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13137* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13138* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13139* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13140* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13141* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13142* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13143* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 13144* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13145* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13146* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13147* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13148* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13149* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13150* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13151* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13152* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13153* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13154* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13155* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13156* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13157* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13158* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13159* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13160* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13161* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13162* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13163* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 13164* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13165* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13166* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13167* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13168* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13169* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13170* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13171* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13172* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13173* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13174* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13175* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13176* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13177* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13178* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13179* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13180* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13181* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13182* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13183* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13184* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13185* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13186* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13187* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13188* RM F(7); COBOL Support: RM F 7 COBOL Support. 13189* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13190* RM G; Numerics: RM G Numerics. 13191* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13192* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13193* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13194* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13195* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13196 13197@end menu 13198 13199@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13200@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{1cd} 13201@section RM 1.1.3(20): Error Detection 13202 13203 13204@quotation 13205 13206"If an implementation detects the use of an unsupported Specialized Needs 13207Annex feature at run time, it should raise @cite{Program_Error} if 13208feasible." 13209@end quotation 13210 13211Not relevant. All specialized needs annex features are either supported, 13212or diagnosed at compile time. 13213 13214@geindex Child Units 13215 13216@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13217@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{1ce} 13218@section RM 1.1.3(31): Child Units 13219 13220 13221@quotation 13222 13223"If an implementation wishes to provide implementation-defined 13224extensions to the functionality of a language-defined library unit, it 13225should normally do so by adding children to the library unit." 13226@end quotation 13227 13228Followed. 13229 13230@geindex Bounded errors 13231 13232@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13233@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{1cf} 13234@section RM 1.1.5(12): Bounded Errors 13235 13236 13237@quotation 13238 13239"If an implementation detects a bounded error or erroneous 13240execution, it should raise @cite{Program_Error}." 13241@end quotation 13242 13243Followed in all cases in which the implementation detects a bounded 13244error or erroneous execution. Not all such situations are detected at 13245runtime. 13246 13247@geindex Pragmas 13248 13249@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13250@anchor{gnat_rm/implementation_advice id2}@anchor{1d0}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{1d1} 13251@section RM 2.8(16): Pragmas 13252 13253 13254@quotation 13255 13256"Normally, implementation-defined pragmas should have no semantic effect 13257for error-free programs; that is, if the implementation-defined pragmas 13258are removed from a working program, the program should still be legal, 13259and should still have the same semantics." 13260@end quotation 13261 13262The following implementation defined pragmas are exceptions to this 13263rule: 13264 13265 13266@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 13267@headitem 13268 13269Pragma 13270 13271@tab 13272 13273Explanation 13274 13275@item 13276 13277@emph{Abort_Defer} 13278 13279@tab 13280 13281Affects semantics 13282 13283@item 13284 13285@emph{Ada_83} 13286 13287@tab 13288 13289Affects legality 13290 13291@item 13292 13293@emph{Assert} 13294 13295@tab 13296 13297Affects semantics 13298 13299@item 13300 13301@emph{CPP_Class} 13302 13303@tab 13304 13305Affects semantics 13306 13307@item 13308 13309@emph{CPP_Constructor} 13310 13311@tab 13312 13313Affects semantics 13314 13315@item 13316 13317@emph{Debug} 13318 13319@tab 13320 13321Affects semantics 13322 13323@item 13324 13325@emph{Interface_Name} 13326 13327@tab 13328 13329Affects semantics 13330 13331@item 13332 13333@emph{Machine_Attribute} 13334 13335@tab 13336 13337Affects semantics 13338 13339@item 13340 13341@emph{Unimplemented_Unit} 13342 13343@tab 13344 13345Affects legality 13346 13347@item 13348 13349@emph{Unchecked_Union} 13350 13351@tab 13352 13353Affects semantics 13354 13355@end multitable 13356 13357 13358In each of the above cases, it is essential to the purpose of the pragma 13359that this advice not be followed. For details see 13360@ref{7,,Implementation Defined Pragmas}. 13361 13362@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 13363@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{1d2} 13364@section RM 2.8(17-19): Pragmas 13365 13366 13367@quotation 13368 13369"Normally, an implementation should not define pragmas that can 13370make an illegal program legal, except as follows: 13371 13372 13373@itemize * 13374 13375@item 13376A pragma used to complete a declaration, such as a pragma @cite{Import}; 13377 13378@item 13379A pragma used to configure the environment by adding, removing, or 13380replacing @cite{library_items}." 13381@end itemize 13382@end quotation 13383 13384See @ref{1d1,,RM 2.8(16); Pragmas}. 13385 13386@geindex Character Sets 13387 13388@geindex Alternative Character Sets 13389 13390@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 13391@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{1d3} 13392@section RM 3.5.2(5): Alternative Character Sets 13393 13394 13395@quotation 13396 13397"If an implementation supports a mode with alternative interpretations 13398for @cite{Character} and @cite{Wide_Character}, the set of graphic 13399characters of @cite{Character} should nevertheless remain a proper 13400subset of the set of graphic characters of @cite{Wide_Character}. Any 13401character set 'localizations' should be reflected in the results of 13402the subprograms defined in the language-defined package 13403@cite{Characters.Handling} (see A.3) available in such a mode. In a mode with 13404an alternative interpretation of @cite{Character}, the implementation should 13405also support a corresponding change in what is a legal 13406@cite{identifier_letter}." 13407@end quotation 13408 13409Not all wide character modes follow this advice, in particular the JIS 13410and IEC modes reflect standard usage in Japan, and in these encoding, 13411the upper half of the Latin-1 set is not part of the wide-character 13412subset, since the most significant bit is used for wide character 13413encoding. However, this only applies to the external forms. Internally 13414there is no such restriction. 13415 13416@geindex Integer types 13417 13418@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 13419@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{1d4} 13420@section RM 3.5.4(28): Integer Types 13421 13422 13423@quotation 13424 13425"An implementation should support @cite{Long_Integer} in addition to 13426@cite{Integer} if the target machine supports 32-bit (or longer) 13427arithmetic. No other named integer subtypes are recommended for package 13428@cite{Standard}. Instead, appropriate named integer subtypes should be 13429provided in the library package @cite{Interfaces} (see B.2)." 13430@end quotation 13431 13432@cite{Long_Integer} is supported. Other standard integer types are supported 13433so this advice is not fully followed. These types 13434are supported for convenient interface to C, and so that all hardware 13435types of the machine are easily available. 13436 13437@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 13438@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{1d5} 13439@section RM 3.5.4(29): Integer Types 13440 13441 13442@quotation 13443 13444"An implementation for a two's complement machine should support 13445modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 13446implementation should support a non-binary modules up to @cite{Integer'Last}." 13447@end quotation 13448 13449Followed. 13450 13451@geindex Enumeration values 13452 13453@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 13454@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{1d6} 13455@section RM 3.5.5(8): Enumeration Values 13456 13457 13458@quotation 13459 13460"For the evaluation of a call on @code{S'Pos} for an enumeration 13461subtype, if the value of the operand does not correspond to the internal 13462code for any enumeration literal of its type (perhaps due to an 13463un-initialized variable), then the implementation should raise 13464@cite{Program_Error}. This is particularly important for enumeration 13465types with noncontiguous internal codes specified by an 13466enumeration_representation_clause." 13467@end quotation 13468 13469Followed. 13470 13471@geindex Float types 13472 13473@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 13474@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{1d7} 13475@section RM 3.5.7(17): Float Types 13476 13477 13478@quotation 13479 13480"An implementation should support @cite{Long_Float} in addition to 13481@cite{Float} if the target machine supports 11 or more digits of 13482precision. No other named floating point subtypes are recommended for 13483package @cite{Standard}. Instead, appropriate named floating point subtypes 13484should be provided in the library package @cite{Interfaces} (see B.2)." 13485@end quotation 13486 13487@cite{Short_Float} and @cite{Long_Long_Float} are also provided. The 13488former provides improved compatibility with other implementations 13489supporting this type. The latter corresponds to the highest precision 13490floating-point type supported by the hardware. On most machines, this 13491will be the same as @cite{Long_Float}, but on some machines, it will 13492correspond to the IEEE extended form. The notable case is all ia32 13493(x86) implementations, where @cite{Long_Long_Float} corresponds to 13494the 80-bit extended precision format supported in hardware on this 13495processor. Note that the 128-bit format on SPARC is not supported, 13496since this is a software rather than a hardware format. 13497 13498@geindex Multidimensional arrays 13499 13500@geindex Arrays 13501@geindex multidimensional 13502 13503@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice 13504@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{1d8} 13505@section RM 3.6.2(11): Multidimensional Arrays 13506 13507 13508@quotation 13509 13510"An implementation should normally represent multidimensional arrays in 13511row-major order, consistent with the notation used for multidimensional 13512array aggregates (see 4.3.3). However, if a pragma @cite{Convention} 13513(@cite{Fortran}, ...) applies to a multidimensional array type, then 13514column-major order should be used instead (see B.5, @cite{Interfacing with Fortran})." 13515@end quotation 13516 13517Followed. 13518 13519@geindex Duration'Small 13520 13521@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 13522@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{1d9} 13523@section RM 9.6(30-31): Duration'Small 13524 13525 13526@quotation 13527 13528"Whenever possible in an implementation, the value of @cite{Duration'Small} 13529should be no greater than 100 microseconds." 13530@end quotation 13531 13532Followed. (@cite{Duration'Small} = 10**(-9)). 13533 13534@quotation 13535 13536"The time base for @cite{delay_relative_statements} should be monotonic; 13537it need not be the same time base as used for @cite{Calendar.Clock}." 13538@end quotation 13539 13540Followed. 13541 13542@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice 13543@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{1da} 13544@section RM 10.2.1(12): Consistent Representation 13545 13546 13547@quotation 13548 13549"In an implementation, a type declared in a pre-elaborated package should 13550have the same representation in every elaboration of a given version of 13551the package, whether the elaborations occur in distinct executions of 13552the same program, or in executions of distinct programs or partitions 13553that include the given version." 13554@end quotation 13555 13556Followed, except in the case of tagged types. Tagged types involve 13557implicit pointers to a local copy of a dispatch table, and these pointers 13558have representations which thus depend on a particular elaboration of the 13559package. It is not easy to see how it would be possible to follow this 13560advice without severely impacting efficiency of execution. 13561 13562@geindex Exception information 13563 13564@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 13565@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{1db} 13566@section RM 11.4.1(19): Exception Information 13567 13568 13569@quotation 13570 13571"@cite{Exception_Message} by default and @cite{Exception_Information} 13572should produce information useful for 13573debugging. @cite{Exception_Message} should be short, about one 13574line. @cite{Exception_Information} can be long. @cite{Exception_Message} 13575should not include the 13576@cite{Exception_Name}. @cite{Exception_Information} should include both 13577the @cite{Exception_Name} and the @cite{Exception_Message}." 13578@end quotation 13579 13580Followed. For each exception that doesn't have a specified 13581@cite{Exception_Message}, the compiler generates one containing the location 13582of the raise statement. This location has the form 'file_name:line', where 13583file_name is the short file name (without path information) and line is the line 13584number in the file. Note that in the case of the Zero Cost Exception 13585mechanism, these messages become redundant with the Exception_Information that 13586contains a full backtrace of the calling sequence, so they are disabled. 13587To disable explicitly the generation of the source location message, use the 13588Pragma @cite{Discard_Names}. 13589 13590@geindex Suppression of checks 13591 13592@geindex Checks 13593@geindex suppression of 13594 13595@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 13596@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{1dc} 13597@section RM 11.5(28): Suppression of Checks 13598 13599 13600@quotation 13601 13602"The implementation should minimize the code executed for checks that 13603have been suppressed." 13604@end quotation 13605 13606Followed. 13607 13608@geindex Representation clauses 13609 13610@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 13611@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{1dd} 13612@section RM 13.1 (21-24): Representation Clauses 13613 13614 13615@quotation 13616 13617"The recommended level of support for all representation items is 13618qualified as follows: 13619 13620An implementation need not support representation items containing 13621nonstatic expressions, except that an implementation should support a 13622representation item for a given entity if each nonstatic expression in 13623the representation item is a name that statically denotes a constant 13624declared before the entity." 13625@end quotation 13626 13627Followed. In fact, GNAT goes beyond the recommended level of support 13628by allowing nonstatic expressions in some representation clauses even 13629without the need to declare constants initialized with the values of 13630such expressions. 13631For example: 13632 13633@example 13634 X : Integer; 13635 Y : Float; 13636 for Y'Address use X'Address;>> 13637 13638 13639"An implementation need not support a specification for the `Size` 13640for a given composite subtype, nor the size or storage place for an 13641object (including a component) of a given composite subtype, unless the 13642constraints on the subtype and its composite subcomponents (if any) are 13643all static constraints." 13644@end example 13645 13646Followed. Size Clauses are not permitted on nonstatic components, as 13647described above. 13648 13649@quotation 13650 13651"An aliased component, or a component whose type is by-reference, should 13652always be allocated at an addressable location." 13653@end quotation 13654 13655Followed. 13656 13657@geindex Packed types 13658 13659@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 13660@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{1de} 13661@section RM 13.2(6-8): Packed Types 13662 13663 13664@quotation 13665 13666"If a type is packed, then the implementation should try to minimize 13667storage allocated to objects of the type, possibly at the expense of 13668speed of accessing components, subject to reasonable complexity in 13669addressing calculations. 13670 13671The recommended level of support pragma @cite{Pack} is: 13672 13673For a packed record type, the components should be packed as tightly as 13674possible subject to the Sizes of the component subtypes, and subject to 13675any @cite{record_representation_clause} that applies to the type; the 13676implementation may, but need not, reorder components or cross aligned 13677word boundaries to improve the packing. A component whose @cite{Size} is 13678greater than the word size may be allocated an integral number of words." 13679@end quotation 13680 13681Followed. Tight packing of arrays is supported for all component sizes 13682up to 64-bits. If the array component size is 1 (that is to say, if 13683the component is a boolean type or an enumeration type with two values) 13684then values of the type are implicitly initialized to zero. This 13685happens both for objects of the packed type, and for objects that have a 13686subcomponent of the packed type. 13687 13688@quotation 13689 13690"An implementation should support Address clauses for imported 13691subprograms." 13692@end quotation 13693 13694Followed. 13695 13696@geindex Address clauses 13697 13698@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 13699@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{1df} 13700@section RM 13.3(14-19): Address Clauses 13701 13702 13703@quotation 13704 13705"For an array @cite{X}, @code{X'Address} should point at the first 13706component of the array, and not at the array bounds." 13707@end quotation 13708 13709Followed. 13710 13711@quotation 13712 13713"The recommended level of support for the @cite{Address} attribute is: 13714 13715@code{X'Address} should produce a useful result if @cite{X} is an 13716object that is aliased or of a by-reference type, or is an entity whose 13717@cite{Address} has been specified." 13718@end quotation 13719 13720Followed. A valid address will be produced even if none of those 13721conditions have been met. If necessary, the object is forced into 13722memory to ensure the address is valid. 13723 13724@quotation 13725 13726"An implementation should support @cite{Address} clauses for imported 13727subprograms." 13728@end quotation 13729 13730Followed. 13731 13732@quotation 13733 13734"Objects (including subcomponents) that are aliased or of a by-reference 13735type should be allocated on storage element boundaries." 13736@end quotation 13737 13738Followed. 13739 13740@quotation 13741 13742"If the @cite{Address} of an object is specified, or it is imported or exported, 13743then the implementation should not perform optimizations based on 13744assumptions of no aliases." 13745@end quotation 13746 13747Followed. 13748 13749@geindex Alignment clauses 13750 13751@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 13752@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{1e0} 13753@section RM 13.3(29-35): Alignment Clauses 13754 13755 13756@quotation 13757 13758"The recommended level of support for the @cite{Alignment} attribute for 13759subtypes is: 13760 13761An implementation should support specified Alignments that are factors 13762and multiples of the number of storage elements per word, subject to the 13763following:" 13764@end quotation 13765 13766Followed. 13767 13768@quotation 13769 13770"An implementation need not support specified Alignments for 13771combinations of Sizes and Alignments that cannot be easily 13772loaded and stored by available machine instructions." 13773@end quotation 13774 13775Followed. 13776 13777@quotation 13778 13779"An implementation need not support specified Alignments that are 13780greater than the maximum @cite{Alignment} the implementation ever returns by 13781default." 13782@end quotation 13783 13784Followed. 13785 13786@quotation 13787 13788"The recommended level of support for the @cite{Alignment} attribute for 13789objects is: 13790 13791Same as above, for subtypes, but in addition:" 13792@end quotation 13793 13794Followed. 13795 13796@quotation 13797 13798"For stand-alone library-level objects of statically constrained 13799subtypes, the implementation should support all alignments 13800supported by the target linker. For example, page alignment is likely to 13801be supported for such objects, but not for subtypes." 13802@end quotation 13803 13804Followed. 13805 13806@geindex Size clauses 13807 13808@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 13809@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{1e1} 13810@section RM 13.3(42-43): Size Clauses 13811 13812 13813@quotation 13814 13815"The recommended level of support for the @cite{Size} attribute of 13816objects is: 13817 13818A @cite{Size} clause should be supported for an object if the specified 13819@cite{Size} is at least as large as its subtype's @cite{Size}, and 13820corresponds to a size in storage elements that is a multiple of the 13821object's @cite{Alignment} (if the @cite{Alignment} is nonzero)." 13822@end quotation 13823 13824Followed. 13825 13826@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 13827@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{1e2} 13828@section RM 13.3(50-56): Size Clauses 13829 13830 13831@quotation 13832 13833"If the @cite{Size} of a subtype is specified, and allows for efficient 13834independent addressability (see 9.10) on the target architecture, then 13835the @cite{Size} of the following objects of the subtype should equal the 13836@cite{Size} of the subtype: 13837 13838Aliased objects (including components)." 13839@end quotation 13840 13841Followed. 13842 13843@quotation 13844 13845"@cite{Size} clause on a composite subtype should not affect the 13846internal layout of components." 13847@end quotation 13848 13849Followed. But note that this can be overridden by use of the implementation 13850pragma Implicit_Packing in the case of packed arrays. 13851 13852@quotation 13853 13854"The recommended level of support for the @cite{Size} attribute of subtypes is: 13855 13856The @cite{Size} (if not specified) of a static discrete or fixed point 13857subtype should be the number of bits needed to represent each value 13858belonging to the subtype using an unbiased representation, leaving space 13859for a sign bit only if the subtype contains negative values. If such a 13860subtype is a first subtype, then an implementation should support a 13861specified @cite{Size} for it that reflects this representation." 13862@end quotation 13863 13864Followed. 13865 13866@quotation 13867 13868"For a subtype implemented with levels of indirection, the @cite{Size} 13869should include the size of the pointers, but not the size of what they 13870point at." 13871@end quotation 13872 13873Followed. 13874 13875@geindex Component_Size clauses 13876 13877@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 13878@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{1e3} 13879@section RM 13.3(71-73): Component Size Clauses 13880 13881 13882@quotation 13883 13884"The recommended level of support for the @cite{Component_Size} 13885attribute is: 13886 13887An implementation need not support specified @cite{Component_Sizes} that are 13888less than the @cite{Size} of the component subtype." 13889@end quotation 13890 13891Followed. 13892 13893@quotation 13894 13895"An implementation should support specified Component_Sizes that 13896are factors and multiples of the word size. For such 13897Component_Sizes, the array should contain no gaps between 13898components. For other Component_Sizes (if supported), the array 13899should contain no gaps between components when packing is also 13900specified; the implementation should forbid this combination in cases 13901where it cannot support a no-gaps representation." 13902@end quotation 13903 13904Followed. 13905 13906@geindex Enumeration representation clauses 13907 13908@geindex Representation clauses 13909@geindex enumeration 13910 13911@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 13912@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{1e4} 13913@section RM 13.4(9-10): Enumeration Representation Clauses 13914 13915 13916@quotation 13917 13918"The recommended level of support for enumeration representation clauses 13919is: 13920 13921An implementation need not support enumeration representation clauses 13922for boolean types, but should at minimum support the internal codes in 13923the range @cite{System.Min_Int .. System.Max_Int}." 13924@end quotation 13925 13926Followed. 13927 13928@geindex Record representation clauses 13929 13930@geindex Representation clauses 13931@geindex records 13932 13933@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 13934@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{1e5} 13935@section RM 13.5.1(17-22): Record Representation Clauses 13936 13937 13938@quotation 13939 13940"The recommended level of support for 13941@cite{record_representation_clauses} is: 13942 13943An implementation should support storage places that can be extracted 13944with a load, mask, shift sequence of machine code, and set with a load, 13945shift, mask, store sequence, given the available machine instructions 13946and run-time model." 13947@end quotation 13948 13949Followed. 13950 13951@quotation 13952 13953"A storage place should be supported if its size is equal to the 13954@cite{Size} of the component subtype, and it starts and ends on a 13955boundary that obeys the @cite{Alignment} of the component subtype." 13956@end quotation 13957 13958Followed. 13959 13960@quotation 13961 13962"If the default bit ordering applies to the declaration of a given type, 13963then for a component whose subtype's @cite{Size} is less than the word 13964size, any storage place that does not cross an aligned word boundary 13965should be supported." 13966@end quotation 13967 13968Followed. 13969 13970@quotation 13971 13972"An implementation may reserve a storage place for the tag field of a 13973tagged type, and disallow other components from overlapping that place." 13974@end quotation 13975 13976Followed. The storage place for the tag field is the beginning of the tagged 13977record, and its size is Address'Size. GNAT will reject an explicit component 13978clause for the tag field. 13979 13980@quotation 13981 13982"An implementation need not support a @cite{component_clause} for a 13983component of an extension part if the storage place is not after the 13984storage places of all components of the parent type, whether or not 13985those storage places had been specified." 13986@end quotation 13987 13988Followed. The above advice on record representation clauses is followed, 13989and all mentioned features are implemented. 13990 13991@geindex Storage place attributes 13992 13993@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 13994@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{1e6} 13995@section RM 13.5.2(5): Storage Place Attributes 13996 13997 13998@quotation 13999 14000"If a component is represented using some form of pointer (such as an 14001offset) to the actual data of the component, and this data is contiguous 14002with the rest of the object, then the storage place attributes should 14003reflect the place of the actual data, not the pointer. If a component is 14004allocated discontinuously from the rest of the object, then a warning 14005should be generated upon reference to one of its storage place 14006attributes." 14007@end quotation 14008 14009Followed. There are no such components in GNAT. 14010 14011@geindex Bit ordering 14012 14013@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 14014@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{1e7} 14015@section RM 13.5.3(7-8): Bit Ordering 14016 14017 14018@quotation 14019 14020"The recommended level of support for the non-default bit ordering is: 14021 14022If @cite{Word_Size} = @cite{Storage_Unit}, then the implementation 14023should support the non-default bit ordering in addition to the default 14024bit ordering." 14025@end quotation 14026 14027Followed. Word size does not equal storage size in this implementation. 14028Thus non-default bit ordering is not supported. 14029 14030@geindex Address 14031@geindex as private type 14032 14033@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 14034@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{1e8} 14035@section RM 13.7(37): Address as Private 14036 14037 14038@quotation 14039 14040"@cite{Address} should be of a private type." 14041@end quotation 14042 14043Followed. 14044 14045@geindex Operations 14046@geindex on `Address` 14047 14048@geindex Address 14049@geindex operations of 14050 14051@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14052@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{1e9} 14053@section RM 13.7.1(16): Address Operations 14054 14055 14056@quotation 14057 14058"Operations in @cite{System} and its children should reflect the target 14059environment semantics as closely as is reasonable. For example, on most 14060machines, it makes sense for address arithmetic to 'wrap around'. 14061Operations that do not make sense should raise @cite{Program_Error}." 14062@end quotation 14063 14064Followed. Address arithmetic is modular arithmetic that wraps around. No 14065operation raises @cite{Program_Error}, since all operations make sense. 14066 14067@geindex Unchecked conversion 14068 14069@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 14070@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{1ea} 14071@section RM 13.9(14-17): Unchecked Conversion 14072 14073 14074@quotation 14075 14076"The @cite{Size} of an array object should not include its bounds; hence, 14077the bounds should not be part of the converted data." 14078@end quotation 14079 14080Followed. 14081 14082@quotation 14083 14084"The implementation should not generate unnecessary run-time checks to 14085ensure that the representation of @cite{S} is a representation of the 14086target type. It should take advantage of the permission to return by 14087reference when possible. Restrictions on unchecked conversions should be 14088avoided unless required by the target environment." 14089@end quotation 14090 14091Followed. There are no restrictions on unchecked conversion. A warning is 14092generated if the source and target types do not have the same size since 14093the semantics in this case may be target dependent. 14094 14095@quotation 14096 14097"The recommended level of support for unchecked conversions is: 14098 14099Unchecked conversions should be supported and should be reversible in 14100the cases where this clause defines the result. To enable meaningful use 14101of unchecked conversion, a contiguous representation should be used for 14102elementary subtypes, for statically constrained array subtypes whose 14103component subtype is one of the subtypes described in this paragraph, 14104and for record subtypes without discriminants whose component subtypes 14105are described in this paragraph." 14106@end quotation 14107 14108Followed. 14109 14110@geindex Heap usage 14111@geindex implicit 14112 14113@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 14114@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{1eb} 14115@section RM 13.11(23-25): Implicit Heap Usage 14116 14117 14118@quotation 14119 14120"An implementation should document any cases in which it dynamically 14121allocates heap storage for a purpose other than the evaluation of an 14122allocator." 14123@end quotation 14124 14125Followed, the only other points at which heap storage is dynamically 14126allocated are as follows: 14127 14128 14129@itemize * 14130 14131@item 14132At initial elaboration time, to allocate dynamically sized global 14133objects. 14134 14135@item 14136To allocate space for a task when a task is created. 14137 14138@item 14139To extend the secondary stack dynamically when needed. The secondary 14140stack is used for returning variable length results. 14141@end itemize 14142 14143 14144@quotation 14145 14146"A default (implementation-provided) storage pool for an 14147access-to-constant type should not have overhead to support deallocation of 14148individual objects." 14149@end quotation 14150 14151Followed. 14152 14153@quotation 14154 14155"A storage pool for an anonymous access type should be created at the 14156point of an allocator for the type, and be reclaimed when the designated 14157object becomes inaccessible." 14158@end quotation 14159 14160Followed. 14161 14162@geindex Unchecked deallocation 14163 14164@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 14165@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{1ec} 14166@section RM 13.11.2(17): Unchecked Deallocation 14167 14168 14169@quotation 14170 14171"For a standard storage pool, @cite{Free} should actually reclaim the 14172storage." 14173@end quotation 14174 14175Followed. 14176 14177@geindex Stream oriented attributes 14178 14179@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 14180@anchor{gnat_rm/implementation_advice rm-13-13-2-17-stream-oriented-attributes}@anchor{1ed} 14181@section RM 13.13.2(17): Stream Oriented Attributes 14182 14183 14184@quotation 14185 14186"If a stream element is the same size as a storage element, then the 14187normal in-memory representation should be used by @cite{Read} and 14188@cite{Write} for scalar objects. Otherwise, @cite{Read} and @cite{Write} 14189should use the smallest number of stream elements needed to represent 14190all values in the base range of the scalar type." 14191@end quotation 14192 14193Followed. By default, GNAT uses the interpretation suggested by AI-195, 14194which specifies using the size of the first subtype. 14195However, such an implementation is based on direct binary 14196representations and is therefore target- and endianness-dependent. 14197To address this issue, GNAT also supplies an alternate implementation 14198of the stream attributes @cite{Read} and @cite{Write}, 14199which uses the target-independent XDR standard representation 14200for scalar types. 14201 14202@geindex XDR representation 14203 14204@geindex Read attribute 14205 14206@geindex Write attribute 14207 14208@geindex Stream oriented attributes 14209 14210The XDR implementation is provided as an alternative body of the 14211@cite{System.Stream_Attributes} package, in the file 14212@code{s-stratt-xdr.adb} in the GNAT library. 14213There is no @code{s-stratt-xdr.ads} file. 14214In order to install the XDR implementation, do the following: 14215 14216 14217@itemize * 14218 14219@item 14220Replace the default implementation of the 14221@cite{System.Stream_Attributes} package with the XDR implementation. 14222For example on a Unix platform issue the commands: 14223 14224@example 14225$ mv s-stratt.adb s-stratt-default.adb 14226$ mv s-stratt-xdr.adb s-stratt.adb 14227@end example 14228 14229@item 14230Rebuild the GNAT run-time library as documented in 14231the @cite{GNAT and Libraries} section of the @cite{GNAT User's Guide}. 14232@end itemize 14233 14234@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 14235@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{1ee} 14236@section RM A.1(52): Names of Predefined Numeric Types 14237 14238 14239@quotation 14240 14241"If an implementation provides additional named predefined integer types, 14242then the names should end with @code{Integer} as in 14243@code{Long_Integer}. If an implementation provides additional named 14244predefined floating point types, then the names should end with 14245@code{Float} as in @code{Long_Float}." 14246@end quotation 14247 14248Followed. 14249 14250@geindex Ada.Characters.Handling 14251 14252@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 14253@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{1ef} 14254@section RM A.3.2(49): @cite{Ada.Characters.Handling} 14255 14256 14257@quotation 14258 14259"If an implementation provides a localized definition of @cite{Character} 14260or @cite{Wide_Character}, then the effects of the subprograms in 14261@cite{Characters.Handling} should reflect the localizations. 14262See also 3.5.2." 14263@end quotation 14264 14265Followed. GNAT provides no such localized definitions. 14266 14267@geindex Bounded-length strings 14268 14269@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 14270@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{1f0} 14271@section RM A.4.4(106): Bounded-Length String Handling 14272 14273 14274@quotation 14275 14276"Bounded string objects should not be implemented by implicit pointers 14277and dynamic allocation." 14278@end quotation 14279 14280Followed. No implicit pointers or dynamic allocation are used. 14281 14282@geindex Random number generation 14283 14284@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 14285@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{1f1} 14286@section RM A.5.2(46-47): Random Number Generation 14287 14288 14289@quotation 14290 14291"Any storage associated with an object of type @cite{Generator} should be 14292reclaimed on exit from the scope of the object." 14293@end quotation 14294 14295Followed. 14296 14297@quotation 14298 14299"If the generator period is sufficiently long in relation to the number 14300of distinct initiator values, then each possible value of 14301@cite{Initiator} passed to @cite{Reset} should initiate a sequence of 14302random numbers that does not, in a practical sense, overlap the sequence 14303initiated by any other value. If this is not possible, then the mapping 14304between initiator values and generator states should be a rapidly 14305varying function of the initiator value." 14306@end quotation 14307 14308Followed. The generator period is sufficiently long for the first 14309condition here to hold true. 14310 14311@geindex Get_Immediate 14312 14313@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 14314@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{1f2} 14315@section RM A.10.7(23): @cite{Get_Immediate} 14316 14317 14318@quotation 14319 14320"The @cite{Get_Immediate} procedures should be implemented with 14321unbuffered input. For a device such as a keyboard, input should be 14322available if a key has already been typed, whereas for a disk 14323file, input should always be available except at end of file. For a file 14324associated with a keyboard-like device, any line-editing features of the 14325underlying operating system should be disabled during the execution of 14326@cite{Get_Immediate}." 14327@end quotation 14328 14329Followed on all targets except VxWorks. For VxWorks, there is no way to 14330provide this functionality that does not result in the input buffer being 14331flushed before the @cite{Get_Immediate} call. A special unit 14332@cite{Interfaces.Vxworks.IO} is provided that contains routines to enable 14333this functionality. 14334 14335@geindex Export 14336 14337@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice 14338@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{1f3} 14339@section RM B.1(39-41): Pragma @cite{Export} 14340 14341 14342@quotation 14343 14344"If an implementation supports pragma @cite{Export} to a given language, 14345then it should also allow the main subprogram to be written in that 14346language. It should support some mechanism for invoking the elaboration 14347of the Ada library units included in the system, and for invoking the 14348finalization of the environment task. On typical systems, the 14349recommended mechanism is to provide two subprograms whose link names are 14350@cite{adainit} and @cite{adafinal}. @cite{adainit} should contain the 14351elaboration code for library units. @cite{adafinal} should contain the 14352finalization code. These subprograms should have no effect the second 14353and subsequent time they are called." 14354@end quotation 14355 14356Followed. 14357 14358@quotation 14359 14360"Automatic elaboration of pre-elaborated packages should be 14361provided when pragma @cite{Export} is supported." 14362@end quotation 14363 14364Followed when the main program is in Ada. If the main program is in a 14365foreign language, then 14366@cite{adainit} must be called to elaborate pre-elaborated 14367packages. 14368 14369@quotation 14370 14371"For each supported convention @cite{L} other than @cite{Intrinsic}, an 14372implementation should support @cite{Import} and @cite{Export} pragmas 14373for objects of @cite{L}-compatible types and for subprograms, and pragma 14374@cite{Convention} for @cite{L}-eligible types and for subprograms, 14375presuming the other language has corresponding features. Pragma 14376@cite{Convention} need not be supported for scalar types." 14377@end quotation 14378 14379Followed. 14380 14381@geindex Package Interfaces 14382 14383@geindex Interfaces 14384 14385@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 14386@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{1f4} 14387@section RM B.2(12-13): Package @cite{Interfaces} 14388 14389 14390@quotation 14391 14392"For each implementation-defined convention identifier, there should be a 14393child package of package Interfaces with the corresponding name. This 14394package should contain any declarations that would be useful for 14395interfacing to the language (implementation) represented by the 14396convention. Any declarations useful for interfacing to any language on 14397the given hardware architecture should be provided directly in 14398@cite{Interfaces}." 14399@end quotation 14400 14401Followed. 14402 14403@quotation 14404 14405"An implementation supporting an interface to C, COBOL, or Fortran should 14406provide the corresponding package or packages described in the following 14407clauses." 14408@end quotation 14409 14410Followed. GNAT provides all the packages described in this section. 14411 14412@geindex C 14413@geindex interfacing with 14414 14415@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 14416@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{1f5} 14417@section RM B.3(63-71): Interfacing with C 14418 14419 14420@quotation 14421 14422"An implementation should support the following interface correspondences 14423between Ada and C." 14424@end quotation 14425 14426Followed. 14427 14428@quotation 14429 14430"An Ada procedure corresponds to a void-returning C function." 14431@end quotation 14432 14433Followed. 14434 14435@quotation 14436 14437"An Ada function corresponds to a non-void C function." 14438@end quotation 14439 14440Followed. 14441 14442@quotation 14443 14444"An Ada @cite{in} scalar parameter is passed as a scalar argument to a C 14445function." 14446@end quotation 14447 14448Followed. 14449 14450@quotation 14451 14452"An Ada @cite{in} parameter of an access-to-object type with designated 14453type @cite{T} is passed as a @code{t*} argument to a C function, 14454where @code{t} is the C type corresponding to the Ada type @cite{T}." 14455@end quotation 14456 14457Followed. 14458 14459@quotation 14460 14461"An Ada access @cite{T} parameter, or an Ada @cite{out} or @cite{in out} 14462parameter of an elementary type @cite{T}, is passed as a @code{t*} 14463argument to a C function, where @code{t} is the C type corresponding to 14464the Ada type @cite{T}. In the case of an elementary @cite{out} or 14465@cite{in out} parameter, a pointer to a temporary copy is used to 14466preserve by-copy semantics." 14467@end quotation 14468 14469Followed. 14470 14471@quotation 14472 14473"An Ada parameter of a record type @cite{T}, of any mode, is passed as a 14474@code{t*} argument to a C function, where @code{t} is the C 14475structure corresponding to the Ada type @cite{T}." 14476@end quotation 14477 14478Followed. This convention may be overridden by the use of the C_Pass_By_Copy 14479pragma, or Convention, or by explicitly specifying the mechanism for a given 14480call using an extended import or export pragma. 14481 14482@quotation 14483 14484"An Ada parameter of an array type with component type @cite{T}, of any 14485mode, is passed as a @code{t*} argument to a C function, where 14486@code{t} is the C type corresponding to the Ada type @cite{T}." 14487@end quotation 14488 14489Followed. 14490 14491@quotation 14492 14493"An Ada parameter of an access-to-subprogram type is passed as a pointer 14494to a C function whose prototype corresponds to the designated 14495subprogram's specification." 14496@end quotation 14497 14498Followed. 14499 14500@geindex COBOL 14501@geindex interfacing with 14502 14503@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 14504@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{1f6} 14505@section RM B.4(95-98): Interfacing with COBOL 14506 14507 14508@quotation 14509 14510"An Ada implementation should support the following interface 14511correspondences between Ada and COBOL." 14512@end quotation 14513 14514Followed. 14515 14516@quotation 14517 14518"An Ada access @cite{T} parameter is passed as a @code{BY REFERENCE} data item of 14519the COBOL type corresponding to @cite{T}." 14520@end quotation 14521 14522Followed. 14523 14524@quotation 14525 14526"An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 14527the corresponding COBOL type." 14528@end quotation 14529 14530Followed. 14531 14532@quotation 14533 14534"Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 14535COBOL type corresponding to the Ada parameter type; for scalars, a local 14536copy is used if necessary to ensure by-copy semantics." 14537@end quotation 14538 14539Followed. 14540 14541@geindex Fortran 14542@geindex interfacing with 14543 14544@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 14545@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{1f7} 14546@section RM B.5(22-26): Interfacing with Fortran 14547 14548 14549@quotation 14550 14551"An Ada implementation should support the following interface 14552correspondences between Ada and Fortran:" 14553@end quotation 14554 14555Followed. 14556 14557@quotation 14558 14559"An Ada procedure corresponds to a Fortran subroutine." 14560@end quotation 14561 14562Followed. 14563 14564@quotation 14565 14566"An Ada function corresponds to a Fortran function." 14567@end quotation 14568 14569Followed. 14570 14571@quotation 14572 14573"An Ada parameter of an elementary, array, or record type @cite{T} is 14574passed as a @cite{T} argument to a Fortran procedure, where @cite{T} is 14575the Fortran type corresponding to the Ada type @cite{T}, and where the 14576INTENT attribute of the corresponding dummy argument matches the Ada 14577formal parameter mode; the Fortran implementation's parameter passing 14578conventions are used. For elementary types, a local copy is used if 14579necessary to ensure by-copy semantics." 14580@end quotation 14581 14582Followed. 14583 14584@quotation 14585 14586"An Ada parameter of an access-to-subprogram type is passed as a 14587reference to a Fortran procedure whose interface corresponds to the 14588designated subprogram's specification." 14589@end quotation 14590 14591Followed. 14592 14593@geindex Machine operations 14594 14595@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 14596@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{1f8} 14597@section RM C.1(3-5): Access to Machine Operations 14598 14599 14600@quotation 14601 14602"The machine code or intrinsic support should allow access to all 14603operations normally available to assembly language programmers for the 14604target environment, including privileged instructions, if any." 14605@end quotation 14606 14607Followed. 14608 14609@quotation 14610 14611"The interfacing pragmas (see Annex B) should support interface to 14612assembler; the default assembler should be associated with the 14613convention identifier @cite{Assembler}." 14614@end quotation 14615 14616Followed. 14617 14618@quotation 14619 14620"If an entity is exported to assembly language, then the implementation 14621should allocate it at an addressable location, and should ensure that it 14622is retained by the linking process, even if not otherwise referenced 14623from the Ada code. The implementation should assume that any call to a 14624machine code or assembler subprogram is allowed to read or update every 14625object that is specified as exported." 14626@end quotation 14627 14628Followed. 14629 14630@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 14631@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{1f9} 14632@section RM C.1(10-16): Access to Machine Operations 14633 14634 14635@quotation 14636 14637"The implementation should ensure that little or no overhead is 14638associated with calling intrinsic and machine-code subprograms." 14639@end quotation 14640 14641Followed for both intrinsics and machine-code subprograms. 14642 14643@quotation 14644 14645"It is recommended that intrinsic subprograms be provided for convenient 14646access to any machine operations that provide special capabilities or 14647efficiency and that are not otherwise available through the language 14648constructs." 14649@end quotation 14650 14651Followed. A full set of machine operation intrinsic subprograms is provided. 14652 14653@quotation 14654 14655"Atomic read-modify-write operations---e.g., test and set, compare and 14656swap, decrement and test, enqueue/dequeue." 14657@end quotation 14658 14659Followed on any target supporting such operations. 14660 14661@quotation 14662 14663"Standard numeric functions---e.g.:, sin, log." 14664@end quotation 14665 14666Followed on any target supporting such operations. 14667 14668@quotation 14669 14670"String manipulation operations---e.g.:, translate and test." 14671@end quotation 14672 14673Followed on any target supporting such operations. 14674 14675@quotation 14676 14677"Vector operations---e.g.:, compare vector against thresholds." 14678@end quotation 14679 14680Followed on any target supporting such operations. 14681 14682@quotation 14683 14684"Direct operations on I/O ports." 14685@end quotation 14686 14687Followed on any target supporting such operations. 14688 14689@geindex Interrupt support 14690 14691@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 14692@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{1fa} 14693@section RM C.3(28): Interrupt Support 14694 14695 14696@quotation 14697 14698"If the @cite{Ceiling_Locking} policy is not in effect, the 14699implementation should provide means for the application to specify which 14700interrupts are to be blocked during protected actions, if the underlying 14701system allows for a finer-grain control of interrupt blocking." 14702@end quotation 14703 14704Followed. The underlying system does not allow for finer-grain control 14705of interrupt blocking. 14706 14707@geindex Protected procedure handlers 14708 14709@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 14710@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{1fb} 14711@section RM C.3.1(20-21): Protected Procedure Handlers 14712 14713 14714@quotation 14715 14716"Whenever possible, the implementation should allow interrupt handlers to 14717be called directly by the hardware." 14718@end quotation 14719 14720Followed on any target where the underlying operating system permits 14721such direct calls. 14722 14723@quotation 14724 14725"Whenever practical, violations of any 14726implementation-defined restrictions should be detected before run time." 14727@end quotation 14728 14729Followed. Compile time warnings are given when possible. 14730 14731@geindex Package `Interrupts` 14732 14733@geindex Interrupts 14734 14735@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 14736@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{1fc} 14737@section RM C.3.2(25): Package @cite{Interrupts} 14738 14739 14740@quotation 14741 14742"If implementation-defined forms of interrupt handler procedures are 14743supported, such as protected procedures with parameters, then for each 14744such form of a handler, a type analogous to @cite{Parameterless_Handler} 14745should be specified in a child package of @cite{Interrupts}, with the 14746same operations as in the predefined package Interrupts." 14747@end quotation 14748 14749Followed. 14750 14751@geindex Pre-elaboration requirements 14752 14753@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 14754@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{1fd} 14755@section RM C.4(14): Pre-elaboration Requirements 14756 14757 14758@quotation 14759 14760"It is recommended that pre-elaborated packages be implemented in such a 14761way that there should be little or no code executed at run time for the 14762elaboration of entities not already covered by the Implementation 14763Requirements." 14764@end quotation 14765 14766Followed. Executable code is generated in some cases, e.g., loops 14767to initialize large arrays. 14768 14769@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 14770@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{1fe} 14771@section RM C.5(8): Pragma @cite{Discard_Names} 14772 14773 14774@quotation 14775 14776"If the pragma applies to an entity, then the implementation should 14777reduce the amount of storage used for storing names associated with that 14778entity." 14779@end quotation 14780 14781Followed. 14782 14783@geindex Package Task_Attributes 14784 14785@geindex Task_Attributes 14786 14787@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 14788@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{1ff} 14789@section RM C.7.2(30): The Package Task_Attributes 14790 14791 14792@quotation 14793 14794"Some implementations are targeted to domains in which memory use at run 14795time must be completely deterministic. For such implementations, it is 14796recommended that the storage for task attributes will be pre-allocated 14797statically and not from the heap. This can be accomplished by either 14798placing restrictions on the number and the size of the task's 14799attributes, or by using the pre-allocated storage for the first @cite{N} 14800attribute objects, and the heap for the others. In the latter case, 14801@cite{N} should be documented." 14802@end quotation 14803 14804Not followed. This implementation is not targeted to such a domain. 14805 14806@geindex Locking Policies 14807 14808@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 14809@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{200} 14810@section RM D.3(17): Locking Policies 14811 14812 14813@quotation 14814 14815"The implementation should use names that end with @code{_Locking} for 14816locking policies defined by the implementation." 14817@end quotation 14818 14819Followed. Two implementation-defined locking policies are defined, 14820whose names (@cite{Inheritance_Locking} and 14821@cite{Concurrent_Readers_Locking}) follow this suggestion. 14822 14823@geindex Entry queuing policies 14824 14825@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 14826@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{201} 14827@section RM D.4(16): Entry Queuing Policies 14828 14829 14830@quotation 14831 14832"Names that end with @code{_Queuing} should be used 14833for all implementation-defined queuing policies." 14834@end quotation 14835 14836Followed. No such implementation-defined queuing policies exist. 14837 14838@geindex Preemptive abort 14839 14840@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 14841@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{202} 14842@section RM D.6(9-10): Preemptive Abort 14843 14844 14845@quotation 14846 14847"Even though the @cite{abort_statement} is included in the list of 14848potentially blocking operations (see 9.5.1), it is recommended that this 14849statement be implemented in a way that never requires the task executing 14850the @cite{abort_statement} to block." 14851@end quotation 14852 14853Followed. 14854 14855@quotation 14856 14857"On a multi-processor, the delay associated with aborting a task on 14858another processor should be bounded; the implementation should use 14859periodic polling, if necessary, to achieve this." 14860@end quotation 14861 14862Followed. 14863 14864@geindex Tasking restrictions 14865 14866@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 14867@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{203} 14868@section RM D.7(21): Tasking Restrictions 14869 14870 14871@quotation 14872 14873"When feasible, the implementation should take advantage of the specified 14874restrictions to produce a more efficient implementation." 14875@end quotation 14876 14877GNAT currently takes advantage of these restrictions by providing an optimized 14878run time when the Ravenscar profile and the GNAT restricted run time set 14879of restrictions are specified. See pragma @cite{Profile (Ravenscar)} and 14880pragma @cite{Profile (Restricted)} for more details. 14881 14882@geindex Time 14883@geindex monotonic 14884 14885@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 14886@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{204} 14887@section RM D.8(47-49): Monotonic Time 14888 14889 14890@quotation 14891 14892"When appropriate, implementations should provide configuration 14893mechanisms to change the value of @cite{Tick}." 14894@end quotation 14895 14896Such configuration mechanisms are not appropriate to this implementation 14897and are thus not supported. 14898 14899@quotation 14900 14901"It is recommended that @cite{Calendar.Clock} and @cite{Real_Time.Clock} 14902be implemented as transformations of the same time base." 14903@end quotation 14904 14905Followed. 14906 14907@quotation 14908 14909"It is recommended that the best time base which exists in 14910the underlying system be available to the application through 14911@cite{Clock}. @cite{Best} may mean highest accuracy or largest range." 14912@end quotation 14913 14914Followed. 14915 14916@geindex Partition communication subsystem 14917 14918@geindex PCS 14919 14920@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 14921@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{205} 14922@section RM E.5(28-29): Partition Communication Subsystem 14923 14924 14925@quotation 14926 14927"Whenever possible, the PCS on the called partition should allow for 14928multiple tasks to call the RPC-receiver with different messages and 14929should allow them to block until the corresponding subprogram body 14930returns." 14931@end quotation 14932 14933Followed by GLADE, a separately supplied PCS that can be used with 14934GNAT. 14935 14936@quotation 14937 14938"The @cite{Write} operation on a stream of type @cite{Params_Stream_Type} 14939should raise @cite{Storage_Error} if it runs out of space trying to 14940write the @cite{Item} into the stream." 14941@end quotation 14942 14943Followed by GLADE, a separately supplied PCS that can be used with 14944GNAT. 14945 14946@geindex COBOL support 14947 14948@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 14949@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{206} 14950@section RM F(7): COBOL Support 14951 14952 14953@quotation 14954 14955"If COBOL (respectively, C) is widely supported in the target 14956environment, implementations supporting the Information Systems Annex 14957should provide the child package @cite{Interfaces.COBOL} (respectively, 14958@cite{Interfaces.C}) specified in Annex B and should support a 14959@cite{convention_identifier} of COBOL (respectively, C) in the interfacing 14960pragmas (see Annex B), thus allowing Ada programs to interface with 14961programs written in that language." 14962@end quotation 14963 14964Followed. 14965 14966@geindex Decimal radix support 14967 14968@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 14969@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{207} 14970@section RM F.1(2): Decimal Radix Support 14971 14972 14973@quotation 14974 14975"Packed decimal should be used as the internal representation for objects 14976of subtype @cite{S} when @cite{S}'Machine_Radix = 10." 14977@end quotation 14978 14979Not followed. GNAT ignores @cite{S}'Machine_Radix and always uses binary 14980representations. 14981 14982@geindex Numerics 14983 14984@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 14985@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{208} 14986@section RM G: Numerics 14987 14988 14989@quotation 14990 14991"If Fortran (respectively, C) is widely supported in the target 14992environment, implementations supporting the Numerics Annex 14993should provide the child package @cite{Interfaces.Fortran} (respectively, 14994@cite{Interfaces.C}) specified in Annex B and should support a 14995@cite{convention_identifier} of Fortran (respectively, C) in the interfacing 14996pragmas (see Annex B), thus allowing Ada programs to interface with 14997programs written in that language." 14998@end quotation 14999 15000Followed. 15001 15002@geindex Complex types 15003 15004@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15005@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{209} 15006@section RM G.1.1(56-58): Complex Types 15007 15008 15009@quotation 15010 15011"Because the usual mathematical meaning of multiplication of a complex 15012operand and a real operand is that of the scaling of both components of 15013the former by the latter, an implementation should not perform this 15014operation by first promoting the real operand to complex type and then 15015performing a full complex multiplication. In systems that, in the 15016future, support an Ada binding to IEC 559:1989, the latter technique 15017will not generate the required result when one of the components of the 15018complex operand is infinite. (Explicit multiplication of the infinite 15019component by the zero component obtained during promotion yields a NaN 15020that propagates into the final result.) Analogous advice applies in the 15021case of multiplication of a complex operand and a pure-imaginary 15022operand, and in the case of division of a complex operand by a real or 15023pure-imaginary operand." 15024@end quotation 15025 15026Not followed. 15027 15028@quotation 15029 15030"Similarly, because the usual mathematical meaning of addition of a 15031complex operand and a real operand is that the imaginary operand remains 15032unchanged, an implementation should not perform this operation by first 15033promoting the real operand to complex type and then performing a full 15034complex addition. In implementations in which the @cite{Signed_Zeros} 15035attribute of the component type is @cite{True} (and which therefore 15036conform to IEC 559:1989 in regard to the handling of the sign of zero in 15037predefined arithmetic operations), the latter technique will not 15038generate the required result when the imaginary component of the complex 15039operand is a negatively signed zero. (Explicit addition of the negative 15040zero to the zero obtained during promotion yields a positive zero.) 15041Analogous advice applies in the case of addition of a complex operand 15042and a pure-imaginary operand, and in the case of subtraction of a 15043complex operand and a real or pure-imaginary operand." 15044@end quotation 15045 15046Not followed. 15047 15048@quotation 15049 15050"Implementations in which @cite{Real'Signed_Zeros} is @cite{True} should 15051attempt to provide a rational treatment of the signs of zero results and 15052result components. As one example, the result of the @cite{Argument} 15053function should have the sign of the imaginary component of the 15054parameter @cite{X} when the point represented by that parameter lies on 15055the positive real axis; as another, the sign of the imaginary component 15056of the @cite{Compose_From_Polar} function should be the same as 15057(respectively, the opposite of) that of the @cite{Argument} parameter when that 15058parameter has a value of zero and the @cite{Modulus} parameter has a 15059nonnegative (respectively, negative) value." 15060@end quotation 15061 15062Followed. 15063 15064@geindex Complex elementary functions 15065 15066@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 15067@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{20a} 15068@section RM G.1.2(49): Complex Elementary Functions 15069 15070 15071@quotation 15072 15073"Implementations in which @cite{Complex_Types.Real'Signed_Zeros} is 15074@cite{True} should attempt to provide a rational treatment of the signs 15075of zero results and result components. For example, many of the complex 15076elementary functions have components that are odd functions of one of 15077the parameter components; in these cases, the result component should 15078have the sign of the parameter component at the origin. Other complex 15079elementary functions have zero components whose sign is opposite that of 15080a parameter component at the origin, or is always positive or always 15081negative." 15082@end quotation 15083 15084Followed. 15085 15086@geindex Accuracy requirements 15087 15088@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 15089@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{20b} 15090@section RM G.2.4(19): Accuracy Requirements 15091 15092 15093@quotation 15094 15095"The versions of the forward trigonometric functions without a 15096@cite{Cycle} parameter should not be implemented by calling the 15097corresponding version with a @cite{Cycle} parameter of 15098@cite{2.0*Numerics.Pi}, since this will not provide the required 15099accuracy in some portions of the domain. For the same reason, the 15100version of @cite{Log} without a @cite{Base} parameter should not be 15101implemented by calling the corresponding version with a @cite{Base} 15102parameter of @cite{Numerics.e}." 15103@end quotation 15104 15105Followed. 15106 15107@geindex Complex arithmetic accuracy 15108 15109@geindex Accuracy 15110@geindex complex arithmetic 15111 15112@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 15113@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{20c} 15114@section RM G.2.6(15): Complex Arithmetic Accuracy 15115 15116 15117@quotation 15118 15119"The version of the @cite{Compose_From_Polar} function without a 15120@cite{Cycle} parameter should not be implemented by calling the 15121corresponding version with a @cite{Cycle} parameter of 15122@cite{2.0*Numerics.Pi}, since this will not provide the required 15123accuracy in some portions of the domain." 15124@end quotation 15125 15126Followed. 15127 15128@geindex Sequential elaboration policy 15129 15130@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15131@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{20d} 15132@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15133 15134 15135@quotation 15136 15137"If the partition elaboration policy is @cite{Sequential} and the 15138Environment task becomes permanently blocked during elaboration then the 15139partition is deadlocked and it is recommended that the partition be 15140immediately terminated." 15141@end quotation 15142 15143Not followed. 15144 15145@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15146@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{20e}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{20f} 15147@chapter Implementation Defined Characteristics 15148 15149 15150In addition to the implementation dependent pragmas and attributes, and the 15151implementation advice, there are a number of other Ada features that are 15152potentially implementation dependent and are designated as 15153implementation-defined. These are mentioned throughout the Ada Reference 15154Manual, and are summarized in Annex M. 15155 15156A requirement for conforming Ada compilers is that they provide 15157documentation describing how the implementation deals with each of these 15158issues. In this chapter you will find each point in Annex M listed, 15159followed by a description of how GNAT 15160handles the implementation dependence. 15161 15162You can use this chapter as a guide to minimizing implementation 15163dependent features in your programs if portability to other compilers 15164and other operating systems is an important consideration. The numbers 15165in each entry below correspond to the paragraph numbers in the Ada 15166Reference Manual. 15167 15168 15169@itemize * 15170 15171@item 15172"Whether or not each recommendation given in Implementation 15173Advice is followed. See 1.1.2(37)." 15174@end itemize 15175 15176See @ref{a,,Implementation Advice}. 15177 15178 15179@itemize * 15180 15181@item 15182"Capacity limitations of the implementation. See 1.1.3(3)." 15183@end itemize 15184 15185The complexity of programs that can be processed is limited only by the 15186total amount of available virtual memory, and disk space for the 15187generated object files. 15188 15189 15190@itemize * 15191 15192@item 15193"Variations from the standard that are impractical to avoid 15194given the implementation's execution environment. See 1.1.3(6)." 15195@end itemize 15196 15197There are no variations from the standard. 15198 15199 15200@itemize * 15201 15202@item 15203"Which code_statements cause external 15204interactions. See 1.1.3(10)." 15205@end itemize 15206 15207Any @cite{code_statement} can potentially cause external interactions. 15208 15209 15210@itemize * 15211 15212@item 15213"The coded representation for the text of an Ada 15214program. See 2.1(4)." 15215@end itemize 15216 15217See separate section on source representation. 15218 15219 15220@itemize * 15221 15222@item 15223"The control functions allowed in comments. See 2.1(14)." 15224@end itemize 15225 15226See separate section on source representation. 15227 15228 15229@itemize * 15230 15231@item 15232"The representation for an end of line. See 2.2(2)." 15233@end itemize 15234 15235See separate section on source representation. 15236 15237 15238@itemize * 15239 15240@item 15241"Maximum supported line length and lexical element 15242length. See 2.2(15)." 15243@end itemize 15244 15245The maximum line length is 255 characters and the maximum length of 15246a lexical element is also 255 characters. This is the default setting 15247if not overridden by the use of compiler switch @emph{-gnaty} (which 15248sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15249line length to be specified to be any value up to 32767. The maximum 15250length of a lexical element is the same as the maximum line length. 15251 15252 15253@itemize * 15254 15255@item 15256"Implementation defined pragmas. See 2.8(14)." 15257@end itemize 15258 15259See @ref{7,,Implementation Defined Pragmas}. 15260 15261 15262@itemize * 15263 15264@item 15265"Effect of pragma @cite{Optimize}. See 2.8(27)." 15266@end itemize 15267 15268Pragma @cite{Optimize}, if given with a @cite{Time} or @cite{Space} 15269parameter, checks that the optimization flag is set, and aborts if it is 15270not. 15271 15272 15273@itemize * 15274 15275@item 15276"The sequence of characters of the value returned by 15277@code{S'Image} when some of the graphic characters of 15278@code{S'Wide_Image} are not defined in @cite{Character}. See 152793.5(37)." 15280@end itemize 15281 15282The sequence of characters is as defined by the wide character encoding 15283method used for the source. See section on source representation for 15284further details. 15285 15286 15287@itemize * 15288 15289@item 15290"The predefined integer types declared in 15291@cite{Standard}. See 3.5.4(25)." 15292@end itemize 15293 15294 15295@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15296@headitem 15297 15298Type 15299 15300@tab 15301 15302Representation 15303 15304@item 15305 15306@emph{Short_Short_Integer} 15307 15308@tab 15309 153108 bit signed 15311 15312@item 15313 15314@emph{Short_Integer} 15315 15316@tab 15317 15318(Short) 16 bit signed 15319 15320@item 15321 15322@emph{Integer} 15323 15324@tab 15325 1532632 bit signed 15327 15328@item 15329 15330@emph{Long_Integer} 15331 15332@tab 15333 1533464 bit signed (on most 64 bit targets, 15335depending on the C definition of long). 1533632 bit signed (all other targets) 15337 15338@item 15339 15340@emph{Long_Long_Integer} 15341 15342@tab 15343 1534464 bit signed 15345 15346@end multitable 15347 15348 15349 15350@itemize * 15351 15352@item 15353"Any nonstandard integer types and the operators defined 15354for them. See 3.5.4(26)." 15355@end itemize 15356 15357There are no nonstandard integer types. 15358 15359 15360@itemize * 15361 15362@item 15363"Any nonstandard real types and the operators defined for 15364them. See 3.5.6(8)." 15365@end itemize 15366 15367There are no nonstandard real types. 15368 15369 15370@itemize * 15371 15372@item 15373"What combinations of requested decimal precision and range 15374are supported for floating point types. See 3.5.7(7)." 15375@end itemize 15376 15377The precision and range is as defined by the IEEE standard. 15378 15379 15380@itemize * 15381 15382@item 15383"The predefined floating point types declared in 15384@cite{Standard}. See 3.5.7(16)." 15385@end itemize 15386 15387 15388@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15389@headitem 15390 15391Type 15392 15393@tab 15394 15395Representation 15396 15397@item 15398 15399@emph{Short_Float} 15400 15401@tab 15402 1540332 bit IEEE short 15404 15405@item 15406 15407@emph{Float} 15408 15409@tab 15410 15411(Short) 32 bit IEEE short 15412 15413@item 15414 15415@emph{Long_Float} 15416 15417@tab 15418 1541964 bit IEEE long 15420 15421@item 15422 15423@emph{Long_Long_Float} 15424 15425@tab 15426 1542764 bit IEEE long (80 bit IEEE long on x86 processors) 15428 15429@end multitable 15430 15431 15432 15433@itemize * 15434 15435@item 15436"The small of an ordinary fixed point type. See 3.5.9(8)." 15437@end itemize 15438 15439@cite{Fine_Delta} is 2**(-63) 15440 15441 15442@itemize * 15443 15444@item 15445"What combinations of small, range, and digits are 15446supported for fixed point types. See 3.5.9(10)." 15447@end itemize 15448 15449Any combinations are permitted that do not result in a small less than 15450@cite{Fine_Delta} and do not result in a mantissa larger than 63 bits. 15451If the mantissa is larger than 53 bits on machines where Long_Long_Float 15452is 64 bits (true of all architectures except ia32), then the output from 15453Text_IO is accurate to only 53 bits, rather than the full mantissa. This 15454is because floating-point conversions are used to convert fixed point. 15455 15456 15457@itemize * 15458 15459@item 15460"The result of @cite{Tags.Expanded_Name} for types declared 15461within an unnamed @cite{block_statement}. See 3.9(10)." 15462@end itemize 15463 15464Block numbers of the form @cite{B`nnn`}, where @cite{nnn} is a 15465decimal integer are allocated. 15466 15467 15468@itemize * 15469 15470@item 15471"Implementation-defined attributes. See 4.1.4(12)." 15472@end itemize 15473 15474See @ref{8,,Implementation Defined Attributes}. 15475 15476 15477@itemize * 15478 15479@item 15480"Any implementation-defined time types. See 9.6(6)." 15481@end itemize 15482 15483There are no implementation-defined time types. 15484 15485 15486@itemize * 15487 15488@item 15489"The time base associated with relative delays." 15490@end itemize 15491 15492See 9.6(20). The time base used is that provided by the C library 15493function @cite{gettimeofday}. 15494 15495 15496@itemize * 15497 15498@item 15499"The time base of the type @cite{Calendar.Time}. See 155009.6(23)." 15501@end itemize 15502 15503The time base used is that provided by the C library function 15504@cite{gettimeofday}. 15505 15506 15507@itemize * 15508 15509@item 15510"The time zone used for package @cite{Calendar} 15511operations. See 9.6(24)." 15512@end itemize 15513 15514The time zone used by package @cite{Calendar} is the current system time zone 15515setting for local time, as accessed by the C library function 15516@cite{localtime}. 15517 15518 15519@itemize * 15520 15521@item 15522"Any limit on @cite{delay_until_statements} of 15523@cite{select_statements}. See 9.6(29)." 15524@end itemize 15525 15526There are no such limits. 15527 15528 15529@itemize * 15530 15531@item 15532"Whether or not two non-overlapping parts of a composite 15533object are independently addressable, in the case where packing, record 15534layout, or @cite{Component_Size} is specified for the object. See 155359.10(1)." 15536@end itemize 15537 15538Separate components are independently addressable if they do not share 15539overlapping storage units. 15540 15541 15542@itemize * 15543 15544@item 15545"The representation for a compilation. See 10.1(2)." 15546@end itemize 15547 15548A compilation is represented by a sequence of files presented to the 15549compiler in a single invocation of the @emph{gcc} command. 15550 15551 15552@itemize * 15553 15554@item 15555"Any restrictions on compilations that contain multiple 15556compilation_units. See 10.1(4)." 15557@end itemize 15558 15559No single file can contain more than one compilation unit, but any 15560sequence of files can be presented to the compiler as a single 15561compilation. 15562 15563 15564@itemize * 15565 15566@item 15567"The mechanisms for creating an environment and for adding 15568and replacing compilation units. See 10.1.4(3)." 15569@end itemize 15570 15571See separate section on compilation model. 15572 15573 15574@itemize * 15575 15576@item 15577"The manner of explicitly assigning library units to a 15578partition. See 10.2(2)." 15579@end itemize 15580 15581If a unit contains an Ada main program, then the Ada units for the partition 15582are determined by recursive application of the rules in the Ada Reference 15583Manual section 10.2(2-6). In other words, the Ada units will be those that 15584are needed by the main program, and then this definition of need is applied 15585recursively to those units, and the partition contains the transitive 15586closure determined by this relationship. In short, all the necessary units 15587are included, with no need to explicitly specify the list. If additional 15588units are required, e.g., by foreign language units, then all units must be 15589mentioned in the context clause of one of the needed Ada units. 15590 15591If the partition contains no main program, or if the main program is in 15592a language other than Ada, then GNAT 15593provides the binder options @emph{-z} and @emph{-n} respectively, and in 15594this case a list of units can be explicitly supplied to the binder for 15595inclusion in the partition (all units needed by these units will also 15596be included automatically). For full details on the use of these 15597options, refer to the @cite{GNAT Make Program gnatmake} in the 15598@cite{GNAT User's Guide}. 15599 15600 15601@itemize * 15602 15603@item 15604"The implementation-defined means, if any, of specifying 15605which compilation units are needed by a given compilation unit. See 1560610.2(2)." 15607@end itemize 15608 15609The units needed by a given compilation unit are as defined in 15610the Ada Reference Manual section 10.2(2-6). There are no 15611implementation-defined pragmas or other implementation-defined 15612means for specifying needed units. 15613 15614 15615@itemize * 15616 15617@item 15618"The manner of designating the main subprogram of a 15619partition. See 10.2(7)." 15620@end itemize 15621 15622The main program is designated by providing the name of the 15623corresponding @code{ALI} file as the input parameter to the binder. 15624 15625 15626@itemize * 15627 15628@item 15629"The order of elaboration of @cite{library_items}. See 1563010.2(18)." 15631@end itemize 15632 15633The first constraint on ordering is that it meets the requirements of 15634Chapter 10 of the Ada Reference Manual. This still leaves some 15635implementation dependent choices, which are resolved by first 15636elaborating bodies as early as possible (i.e., in preference to specs 15637where there is a choice), and second by evaluating the immediate with 15638clauses of a unit to determine the probably best choice, and 15639third by elaborating in alphabetical order of unit names 15640where a choice still remains. 15641 15642 15643@itemize * 15644 15645@item 15646"Parameter passing and function return for the main 15647subprogram. See 10.2(21)." 15648@end itemize 15649 15650The main program has no parameters. It may be a procedure, or a function 15651returning an integer type. In the latter case, the returned integer 15652value is the return code of the program (overriding any value that 15653may have been set by a call to @cite{Ada.Command_Line.Set_Exit_Status}). 15654 15655 15656@itemize * 15657 15658@item 15659"The mechanisms for building and running partitions. See 1566010.2(24)." 15661@end itemize 15662 15663GNAT itself supports programs with only a single partition. The GNATDIST 15664tool provided with the GLADE package (which also includes an implementation 15665of the PCS) provides a completely flexible method for building and running 15666programs consisting of multiple partitions. See the separate GLADE manual 15667for details. 15668 15669 15670@itemize * 15671 15672@item 15673"The details of program execution, including program 15674termination. See 10.2(25)." 15675@end itemize 15676 15677See separate section on compilation model. 15678 15679 15680@itemize * 15681 15682@item 15683"The semantics of any non-active partitions supported by the 15684implementation. See 10.2(28)." 15685@end itemize 15686 15687Passive partitions are supported on targets where shared memory is 15688provided by the operating system. See the GLADE reference manual for 15689further details. 15690 15691 15692@itemize * 15693 15694@item 15695"The information returned by @cite{Exception_Message}. See 1569611.4.1(10)." 15697@end itemize 15698 15699Exception message returns the null string unless a specific message has 15700been passed by the program. 15701 15702 15703@itemize * 15704 15705@item 15706"The result of @cite{Exceptions.Exception_Name} for types 15707declared within an unnamed @cite{block_statement}. See 11.4.1(12)." 15708@end itemize 15709 15710Blocks have implementation defined names of the form @cite{B`nnn`} 15711where @cite{nnn} is an integer. 15712 15713 15714@itemize * 15715 15716@item 15717"The information returned by 15718@cite{Exception_Information}. See 11.4.1(13)." 15719@end itemize 15720 15721@cite{Exception_Information} returns a string in the following format: 15722 15723@example 15724*Exception_Name:* nnnnn 15725*Message:* mmmmm 15726*PID:* ppp 15727*Load address:* 0xhhhh 15728*Call stack traceback locations:* 157290xhhhh 0xhhhh 0xhhhh ... 0xhhh 15730@end example 15731 15732where 15733 15734@quotation 15735 15736 15737@itemize * 15738 15739@item 15740@cite{nnnn} is the fully qualified name of the exception in all upper 15741case letters. This line is always present. 15742 15743@item 15744@cite{mmmm} is the message (this line present only if message is non-null) 15745 15746@item 15747@cite{ppp} is the Process Id value as a decimal integer (this line is 15748present only if the Process Id is nonzero). Currently we are 15749not making use of this field. 15750 15751@item 15752The Load address line, the Call stack traceback locations line and the 15753following values are present only if at least one traceback location was 15754recorded. The Load address indicates the address at which the main executable 15755was loaded; this line may not be present if operating system hasn't relocated 15756the main executable. The values are given in C style format, with lower case 15757letters for a-f, and only as many digits present as are necessary. 15758The line terminator sequence at the end of each line, including 15759the last line is a single @cite{LF} character (@cite{16#0A#}). 15760@end itemize 15761@end quotation 15762 15763 15764@itemize * 15765 15766@item 15767"Implementation-defined check names. See 11.5(27)." 15768@end itemize 15769 15770The implementation defined check names include Alignment_Check, 15771Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 15772Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 15773program can add implementation-defined check names by means of the pragma 15774Check_Name. See the description of pragma @cite{Suppress} for full details. 15775 15776 15777@itemize * 15778 15779@item 15780"The interpretation of each aspect of representation. See 1578113.1(20)." 15782@end itemize 15783 15784See separate section on data representations. 15785 15786 15787@itemize * 15788 15789@item 15790"Any restrictions placed upon representation items. See 1579113.1(20)." 15792@end itemize 15793 15794See separate section on data representations. 15795 15796 15797@itemize * 15798 15799@item 15800"The meaning of @cite{Size} for indefinite subtypes. See 1580113.3(48)." 15802@end itemize 15803 15804Size for an indefinite subtype is the maximum possible size, except that 15805for the case of a subprogram parameter, the size of the parameter object 15806is the actual size. 15807 15808 15809@itemize * 15810 15811@item 15812"The default external representation for a type tag. See 1581313.3(75)." 15814@end itemize 15815 15816The default external representation for a type tag is the fully expanded 15817name of the type in upper case letters. 15818 15819 15820@itemize * 15821 15822@item 15823"What determines whether a compilation unit is the same in 15824two different partitions. See 13.3(76)." 15825@end itemize 15826 15827A compilation unit is the same in two different partitions if and only 15828if it derives from the same source file. 15829 15830 15831@itemize * 15832 15833@item 15834"Implementation-defined components. See 13.5.1(15)." 15835@end itemize 15836 15837The only implementation defined component is the tag for a tagged type, 15838which contains a pointer to the dispatching table. 15839 15840 15841@itemize * 15842 15843@item 15844"If @cite{Word_Size} = @cite{Storage_Unit}, the default bit 15845ordering. See 13.5.3(5)." 15846@end itemize 15847 15848@cite{Word_Size} (32) is not the same as @cite{Storage_Unit} (8) for this 15849implementation, so no non-default bit ordering is supported. The default 15850bit ordering corresponds to the natural endianness of the target architecture. 15851 15852 15853@itemize * 15854 15855@item 15856"The contents of the visible part of package @cite{System} 15857and its language-defined children. See 13.7(2)." 15858@end itemize 15859 15860See the definition of these packages in files @code{system.ads} and 15861@code{s-stoele.ads}. Note that two declarations are added to package 15862System. 15863 15864@example 15865Max_Priority : constant Positive := Priority'Last; 15866Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 15867@end example 15868 15869 15870@itemize * 15871 15872@item 15873"The contents of the visible part of package 15874@cite{System.Machine_Code}, and the meaning of 15875@cite{code_statements}. See 13.8(7)." 15876@end itemize 15877 15878See the definition and documentation in file @code{s-maccod.ads}. 15879 15880 15881@itemize * 15882 15883@item 15884"The effect of unchecked conversion. See 13.9(11)." 15885@end itemize 15886 15887Unchecked conversion between types of the same size 15888results in an uninterpreted transmission of the bits from one type 15889to the other. If the types are of unequal sizes, then in the case of 15890discrete types, a shorter source is first zero or sign extended as 15891necessary, and a shorter target is simply truncated on the left. 15892For all non-discrete types, the source is first copied if necessary 15893to ensure that the alignment requirements of the target are met, then 15894a pointer is constructed to the source value, and the result is obtained 15895by dereferencing this pointer after converting it to be a pointer to the 15896target type. Unchecked conversions where the target subtype is an 15897unconstrained array are not permitted. If the target alignment is 15898greater than the source alignment, then a copy of the result is 15899made with appropriate alignment 15900 15901 15902@itemize * 15903 15904@item 15905"The semantics of operations on invalid representations. 15906See 13.9.2(10-11)." 15907@end itemize 15908 15909For assignments and other operations where the use of invalid values cannot 15910result in erroneous behavior, the compiler ignores the possibility of invalid 15911values. An exception is raised at the point where an invalid value would 15912result in erroneous behavior. For example executing: 15913 15914@example 15915procedure invalidvals is 15916 X : Integer := -1; 15917 Y : Natural range 1 .. 10; 15918 for Y'Address use X'Address; 15919 Z : Natural range 1 .. 10; 15920 A : array (Natural range 1 .. 10) of Integer; 15921begin 15922 Z := Y; -- no exception 15923 A (Z) := 3; -- exception raised; 15924end; 15925@end example 15926 15927As indicated, an exception is raised on the array assignment, but not 15928on the simple assignment of the invalid negative value from Y to Z. 15929 15930 15931@itemize * 15932 15933@item 15934"The manner of choosing a storage pool for an access type 15935when @cite{Storage_Pool} is not specified for the type. See 13.11(17)." 15936@end itemize 15937 15938There are 3 different standard pools used by the compiler when 15939@cite{Storage_Pool} is not specified depending whether the type is local 15940to a subprogram or defined at the library level and whether 15941@cite{Storage_Size`is specified or not. See documentation in the runtime library units `System.Pool_Global}, @cite{System.Pool_Size} and 15942@cite{System.Pool_Local} in files @code{s-poosiz.ads}, 15943@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 15944default pools used. 15945 15946 15947@itemize * 15948 15949@item 15950"Whether or not the implementation provides user-accessible 15951names for the standard pool type(s). See 13.11(17)." 15952@end itemize 15953 15954See documentation in the sources of the run time mentioned in the previous 15955paragraph. All these pools are accessible by means of @cite{with}'ing 15956these units. 15957 15958 15959@itemize * 15960 15961@item 15962"The meaning of @cite{Storage_Size}. See 13.11(18)." 15963@end itemize 15964 15965@cite{Storage_Size} is measured in storage units, and refers to the 15966total space available for an access type collection, or to the primary 15967stack space for a task. 15968 15969 15970@itemize * 15971 15972@item 15973"Implementation-defined aspects of storage pools. See 1597413.11(22)." 15975@end itemize 15976 15977See documentation in the sources of the run time mentioned in the 15978paragraph about standard storage pools above 15979for details on GNAT-defined aspects of storage pools. 15980 15981 15982@itemize * 15983 15984@item 15985"The set of restrictions allowed in a pragma 15986@cite{Restrictions}. See 13.12(7)." 15987@end itemize 15988 15989See @ref{9,,Standard and Implementation Defined Restrictions}. 15990 15991 15992@itemize * 15993 15994@item 15995"The consequences of violating limitations on 15996@cite{Restrictions} pragmas. See 13.12(9)." 15997@end itemize 15998 15999Restrictions that can be checked at compile time result in illegalities 16000if violated. Currently there are no other consequences of violating 16001restrictions. 16002 16003 16004@itemize * 16005 16006@item 16007"The representation used by the @cite{Read} and 16008@cite{Write} attributes of elementary types in terms of stream 16009elements. See 13.13.2(9)." 16010@end itemize 16011 16012The representation is the in-memory representation of the base type of 16013the type, using the number of bits corresponding to the 16014@code{type'Size} value, and the natural ordering of the machine. 16015 16016 16017@itemize * 16018 16019@item 16020"The names and characteristics of the numeric subtypes 16021declared in the visible part of package @cite{Standard}. See A.1(3)." 16022@end itemize 16023 16024See items describing the integer and floating-point types supported. 16025 16026 16027@itemize * 16028 16029@item 16030"The string returned by @cite{Character_Set_Version}. 16031See A.3.5(3)." 16032@end itemize 16033 16034@cite{Ada.Wide_Characters.Handling.Character_Set_Version} returns 16035the string "Unicode 4.0", referring to version 4.0 of the 16036Unicode specification. 16037 16038 16039@itemize * 16040 16041@item 16042"The accuracy actually achieved by the elementary 16043functions. See A.5.1(1)." 16044@end itemize 16045 16046The elementary functions correspond to the functions available in the C 16047library. Only fast math mode is implemented. 16048 16049 16050@itemize * 16051 16052@item 16053"The sign of a zero result from some of the operators or 16054functions in @cite{Numerics.Generic_Elementary_Functions}, when 16055@cite{Float_Type'Signed_Zeros} is @cite{True}. See A.5.1(46)." 16056@end itemize 16057 16058The sign of zeroes follows the requirements of the IEEE 754 standard on 16059floating-point. 16060 16061 16062@itemize * 16063 16064@item 16065"The value of 16066@cite{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)." 16067@end itemize 16068 16069Maximum image width is 6864, see library file @code{s-rannum.ads}. 16070 16071 16072@itemize * 16073 16074@item 16075"The value of 16076@cite{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)." 16077@end itemize 16078 16079Maximum image width is 6864, see library file @code{s-rannum.ads}. 16080 16081 16082@itemize * 16083 16084@item 16085"The algorithms for random number generation. See 16086A.5.2(32)." 16087@end itemize 16088 16089The algorithm is the Mersenne Twister, as documented in the source file 16090@code{s-rannum.adb}. This version of the algorithm has a period of 160912**19937-1. 16092 16093 16094@itemize * 16095 16096@item 16097"The string representation of a random number generator's 16098state. See A.5.2(38)." 16099@end itemize 16100 16101The value returned by the Image function is the concatenation of 16102the fixed-width decimal representations of the 624 32-bit integers 16103of the state vector. 16104 16105 16106@itemize * 16107 16108@item 16109"The minimum time interval between calls to the 16110time-dependent Reset procedure that are guaranteed to initiate different 16111random number sequences. See A.5.2(45)." 16112@end itemize 16113 16114The minimum period between reset calls to guarantee distinct series of 16115random numbers is one microsecond. 16116 16117 16118@itemize * 16119 16120@item 16121"The values of the @cite{Model_Mantissa}, 16122@cite{Model_Emin}, @cite{Model_Epsilon}, @cite{Model}, 16123@cite{Safe_First}, and @cite{Safe_Last} attributes, if the Numerics 16124Annex is not supported. See A.5.3(72)." 16125@end itemize 16126 16127Run the compiler with @emph{-gnatS} to produce a listing of package 16128@cite{Standard}, has the values of all numeric attributes. 16129 16130 16131@itemize * 16132 16133@item 16134"Any implementation-defined characteristics of the 16135input-output packages. See A.7(14)." 16136@end itemize 16137 16138There are no special implementation defined characteristics for these 16139packages. 16140 16141 16142@itemize * 16143 16144@item 16145"The value of @cite{Buffer_Size} in @cite{Storage_IO}. See 16146A.9(10)." 16147@end itemize 16148 16149All type representations are contiguous, and the @cite{Buffer_Size} is 16150the value of @code{type'Size} rounded up to the next storage unit 16151boundary. 16152 16153 16154@itemize * 16155 16156@item 16157"External files for standard input, standard output, and 16158standard error See A.10(5)." 16159@end itemize 16160 16161These files are mapped onto the files provided by the C streams 16162libraries. See source file @code{i-cstrea.ads} for further details. 16163 16164 16165@itemize * 16166 16167@item 16168"The accuracy of the value produced by @cite{Put}. See 16169A.10.9(36)." 16170@end itemize 16171 16172If more digits are requested in the output than are represented by the 16173precision of the value, zeroes are output in the corresponding least 16174significant digit positions. 16175 16176 16177@itemize * 16178 16179@item 16180"The meaning of @cite{Argument_Count}, @cite{Argument}, and 16181@cite{Command_Name}. See A.15(1)." 16182@end itemize 16183 16184These are mapped onto the @cite{argv} and @cite{argc} parameters of the 16185main program in the natural manner. 16186 16187 16188@itemize * 16189 16190@item 16191"The interpretation of the @cite{Form} parameter in procedure 16192@cite{Create_Directory}. See A.16(56)." 16193@end itemize 16194 16195The @cite{Form} parameter is not used. 16196 16197 16198@itemize * 16199 16200@item 16201"The interpretation of the @cite{Form} parameter in procedure 16202@cite{Create_Path}. See A.16(60)." 16203@end itemize 16204 16205The @cite{Form} parameter is not used. 16206 16207 16208@itemize * 16209 16210@item 16211"The interpretation of the @cite{Form} parameter in procedure 16212@cite{Copy_File}. See A.16(68)." 16213@end itemize 16214 16215The @cite{Form} parameter is case-insensitive. 16216Two fields are recognized in the @cite{Form} parameter: 16217 16218@example 16219*preserve=<value>* 16220*mode=<value>* 16221@end example 16222 16223<value> starts immediately after the character '=' and ends with the 16224character immediately preceding the next comma (',') or with the last 16225character of the parameter. 16226 16227The only possible values for preserve= are: 16228 16229 16230@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16231@headitem 16232 16233Value 16234 16235@tab 16236 16237Meaning 16238 16239@item 16240 16241@emph{no_attributes} 16242 16243@tab 16244 16245Do not try to preserve any file attributes. This is the 16246default if no preserve= is found in Form. 16247 16248@item 16249 16250@emph{all_attributes} 16251 16252@tab 16253 16254Try to preserve all file attributes (timestamps, access rights). 16255 16256@item 16257 16258@emph{timestamps} 16259 16260@tab 16261 16262Preserve the timestamp of the copied file, but not the other 16263file attributes. 16264 16265@end multitable 16266 16267 16268The only possible values for mode= are: 16269 16270 16271@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16272@headitem 16273 16274Value 16275 16276@tab 16277 16278Meaning 16279 16280@item 16281 16282@emph{copy} 16283 16284@tab 16285 16286Only do the copy if the destination file does not already exist. 16287If it already exists, Copy_File fails. 16288 16289@item 16290 16291@emph{overwrite} 16292 16293@tab 16294 16295Copy the file in all cases. Overwrite an already existing destination file. 16296 16297@item 16298 16299@emph{append} 16300 16301@tab 16302 16303Append the original file to the destination file. If the destination file 16304does not exist, the destination file is a copy of the source file. 16305When mode=append, the field preserve=, if it exists, is not taken into account. 16306 16307@end multitable 16308 16309 16310If the Form parameter includes one or both of the fields and the value or 16311values are incorrect, Copy_file fails with Use_Error. 16312 16313Examples of correct Forms: 16314 16315@example 16316Form => "preserve=no_attributes,mode=overwrite" (the default) 16317Form => "mode=append" 16318Form => "mode=copy, preserve=all_attributes" 16319@end example 16320 16321Examples of incorrect Forms: 16322 16323@example 16324Form => "preserve=junk" 16325Form => "mode=internal, preserve=timestamps" 16326@end example 16327 16328 16329@itemize * 16330 16331@item 16332"The interpretation of the @cite{Pattern} parameter, when not the null string, 16333in the @cite{Start_Search} and @cite{Search} procedures. 16334See A.16(104) and A.16(112)." 16335@end itemize 16336 16337When the @cite{Pattern} parameter is not the null string, it is interpreted 16338according to the syntax of regular expressions as defined in the 16339@cite{GNAT.Regexp} package. 16340 16341See @ref{210,,GNAT.Regexp (g-regexp.ads)}. 16342 16343 16344@itemize * 16345 16346@item 16347"Implementation-defined convention names. See B.1(11)." 16348@end itemize 16349 16350The following convention names are supported 16351 16352 16353@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16354@headitem 16355 16356Convention Name 16357 16358@tab 16359 16360Interpretation 16361 16362@item 16363 16364@emph{Ada} 16365 16366@tab 16367 16368Ada 16369 16370@item 16371 16372@emph{Ada_Pass_By_Copy} 16373 16374@tab 16375 16376Allowed for any types except by-reference types such as limited 16377records. Compatible with convention Ada, but causes any parameters 16378with this convention to be passed by copy. 16379 16380@item 16381 16382@emph{Ada_Pass_By_Reference} 16383 16384@tab 16385 16386Allowed for any types except by-copy types such as scalars. 16387Compatible with convention Ada, but causes any parameters 16388with this convention to be passed by reference. 16389 16390@item 16391 16392@emph{Assembler} 16393 16394@tab 16395 16396Assembly language 16397 16398@item 16399 16400@emph{Asm} 16401 16402@tab 16403 16404Synonym for Assembler 16405 16406@item 16407 16408@emph{Assembly} 16409 16410@tab 16411 16412Synonym for Assembler 16413 16414@item 16415 16416@emph{C} 16417 16418@tab 16419 16420C 16421 16422@item 16423 16424@emph{C_Pass_By_Copy} 16425 16426@tab 16427 16428Allowed only for record types, like C, but also notes that record 16429is to be passed by copy rather than reference. 16430 16431@item 16432 16433@emph{COBOL} 16434 16435@tab 16436 16437COBOL 16438 16439@item 16440 16441@emph{C_Plus_Plus (or CPP)} 16442 16443@tab 16444 16445C++ 16446 16447@item 16448 16449@emph{Default} 16450 16451@tab 16452 16453Treated the same as C 16454 16455@item 16456 16457@emph{External} 16458 16459@tab 16460 16461Treated the same as C 16462 16463@item 16464 16465@emph{Fortran} 16466 16467@tab 16468 16469Fortran 16470 16471@item 16472 16473@emph{Intrinsic} 16474 16475@tab 16476 16477For support of pragma @cite{Import} with convention Intrinsic, see 16478separate section on Intrinsic Subprograms. 16479 16480@item 16481 16482@emph{Stdcall} 16483 16484@tab 16485 16486Stdcall (used for Windows implementations only). This convention correspond 16487to the WINAPI (previously called Pascal convention) C/C++ convention under 16488Windows. A routine with this convention cleans the stack before 16489exit. This pragma cannot be applied to a dispatching call. 16490 16491@item 16492 16493@emph{DLL} 16494 16495@tab 16496 16497Synonym for Stdcall 16498 16499@item 16500 16501@emph{Win32} 16502 16503@tab 16504 16505Synonym for Stdcall 16506 16507@item 16508 16509@emph{Stubbed} 16510 16511@tab 16512 16513Stubbed is a special convention used to indicate that the body of the 16514subprogram will be entirely ignored. Any call to the subprogram 16515is converted into a raise of the @cite{Program_Error} exception. If a 16516pragma @cite{Import} specifies convention @cite{stubbed} then no body need 16517be present at all. This convention is useful during development for the 16518inclusion of subprograms whose body has not yet been written. 16519In addition, all otherwise unrecognized convention names are also 16520treated as being synonymous with convention C. In all implementations 16521except for VMS, use of such other names results in a warning. In VMS 16522implementations, these names are accepted silently. 16523 16524@end multitable 16525 16526 16527 16528@itemize * 16529 16530@item 16531"The meaning of link names. See B.1(36)." 16532@end itemize 16533 16534Link names are the actual names used by the linker. 16535 16536 16537@itemize * 16538 16539@item 16540"The manner of choosing link names when neither the link 16541name nor the address of an imported or exported entity is specified. See 16542B.1(36)." 16543@end itemize 16544 16545The default linker name is that which would be assigned by the relevant 16546external language, interpreting the Ada name as being in all lower case 16547letters. 16548 16549 16550@itemize * 16551 16552@item 16553"The effect of pragma @cite{Linker_Options}. See B.1(37)." 16554@end itemize 16555 16556The string passed to @cite{Linker_Options} is presented uninterpreted as 16557an argument to the link command, unless it contains ASCII.NUL characters. 16558NUL characters if they appear act as argument separators, so for example 16559 16560@example 16561pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 16562@end example 16563 16564causes two separate arguments @cite{-labc} and @cite{-ldef} to be passed to the 16565linker. The order of linker options is preserved for a given unit. The final 16566list of options passed to the linker is in reverse order of the elaboration 16567order. For example, linker options for a body always appear before the options 16568from the corresponding package spec. 16569 16570 16571@itemize * 16572 16573@item 16574"The contents of the visible part of package 16575@cite{Interfaces} and its language-defined descendants. See B.2(1)." 16576@end itemize 16577 16578See files with prefix @code{i-} in the distributed library. 16579 16580 16581@itemize * 16582 16583@item 16584"Implementation-defined children of package 16585@cite{Interfaces}. The contents of the visible part of package 16586@cite{Interfaces}. See B.2(11)." 16587@end itemize 16588 16589See files with prefix @code{i-} in the distributed library. 16590 16591 16592@itemize * 16593 16594@item 16595"The types @cite{Floating}, @cite{Long_Floating}, 16596@cite{Binary}, @cite{Long_Binary}, @cite{Decimal_ Element}, and 16597@cite{COBOL_Character}; and the initialization of the variables 16598@cite{Ada_To_COBOL} and @cite{COBOL_To_Ada}, in 16599@cite{Interfaces.COBOL}. See B.4(50)." 16600@end itemize 16601 16602 16603@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16604@headitem 16605 16606COBOL 16607 16608@tab 16609 16610Ada 16611 16612@item 16613 16614@emph{Floating} 16615 16616@tab 16617 16618Float 16619 16620@item 16621 16622@emph{Long_Floating} 16623 16624@tab 16625 16626(Floating) Long_Float 16627 16628@item 16629 16630@emph{Binary} 16631 16632@tab 16633 16634Integer 16635 16636@item 16637 16638@emph{Long_Binary} 16639 16640@tab 16641 16642Long_Long_Integer 16643 16644@item 16645 16646@emph{Decimal_Element} 16647 16648@tab 16649 16650Character 16651 16652@item 16653 16654@emph{COBOL_Character} 16655 16656@tab 16657 16658Character 16659 16660@end multitable 16661 16662 16663For initialization, see the file @code{i-cobol.ads} in the distributed library. 16664 16665 16666@itemize * 16667 16668@item 16669"Support for access to machine instructions. See C.1(1)." 16670@end itemize 16671 16672See documentation in file @code{s-maccod.ads} in the distributed library. 16673 16674 16675@itemize * 16676 16677@item 16678"Implementation-defined aspects of access to machine 16679operations. See C.1(9)." 16680@end itemize 16681 16682See documentation in file @code{s-maccod.ads} in the distributed library. 16683 16684 16685@itemize * 16686 16687@item 16688"Implementation-defined aspects of interrupts. See C.3(2)." 16689@end itemize 16690 16691Interrupts are mapped to signals or conditions as appropriate. See 16692definition of unit 16693@cite{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details 16694on the interrupts supported on a particular target. 16695 16696 16697@itemize * 16698 16699@item 16700"Implementation-defined aspects of pre-elaboration. See 16701C.4(13)." 16702@end itemize 16703 16704GNAT does not permit a partition to be restarted without reloading, 16705except under control of the debugger. 16706 16707 16708@itemize * 16709 16710@item 16711"The semantics of pragma @cite{Discard_Names}. See C.5(7)." 16712@end itemize 16713 16714Pragma @cite{Discard_Names} causes names of enumeration literals to 16715be suppressed. In the presence of this pragma, the Image attribute 16716provides the image of the Pos of the literal, and Value accepts 16717Pos values. 16718 16719 16720@itemize * 16721 16722@item 16723"The result of the @cite{Task_Identification.Image} 16724attribute. See C.7.1(7)." 16725@end itemize 16726 16727The result of this attribute is a string that identifies 16728the object or component that denotes a given task. If a variable @cite{Var} 16729has a task type, the image for this task will have the form @cite{Var_`XXXXXXXX`}, 16730where the suffix 16731is the hexadecimal representation of the virtual address of the corresponding 16732task control block. If the variable is an array of tasks, the image of each 16733task will have the form of an indexed component indicating the position of a 16734given task in the array, e.g., @cite{Group(5)_`XXXXXXX`}. If the task is a 16735component of a record, the image of the task will have the form of a selected 16736component. These rules are fully recursive, so that the image of a task that 16737is a subcomponent of a composite object corresponds to the expression that 16738designates this task. 16739 16740If a task is created by an allocator, its image depends on the context. If the 16741allocator is part of an object declaration, the rules described above are used 16742to construct its image, and this image is not affected by subsequent 16743assignments. If the allocator appears within an expression, the image 16744includes only the name of the task type. 16745 16746If the configuration pragma Discard_Names is present, or if the restriction 16747No_Implicit_Heap_Allocation is in effect, the image reduces to 16748the numeric suffix, that is to say the hexadecimal representation of the 16749virtual address of the control block of the task. 16750 16751 16752@itemize * 16753 16754@item 16755"The value of @cite{Current_Task} when in a protected entry 16756or interrupt handler. See C.7.1(17)." 16757@end itemize 16758 16759Protected entries or interrupt handlers can be executed by any 16760convenient thread, so the value of @cite{Current_Task} is undefined. 16761 16762 16763@itemize * 16764 16765@item 16766"The effect of calling @cite{Current_Task} from an entry 16767body or interrupt handler. See C.7.1(19)." 16768@end itemize 16769 16770The effect of calling @cite{Current_Task} from an entry body or 16771interrupt handler is to return the identification of the task currently 16772executing the code. 16773 16774 16775@itemize * 16776 16777@item 16778"Implementation-defined aspects of 16779@cite{Task_Attributes}. See C.7.2(19)." 16780@end itemize 16781 16782There are no implementation-defined aspects of @cite{Task_Attributes}. 16783 16784 16785@itemize * 16786 16787@item 16788"Values of all @cite{Metrics}. See D(2)." 16789@end itemize 16790 16791The metrics information for GNAT depends on the performance of the 16792underlying operating system. The sources of the run-time for tasking 16793implementation, together with the output from @emph{-gnatG} can be 16794used to determine the exact sequence of operating systems calls made 16795to implement various tasking constructs. Together with appropriate 16796information on the performance of the underlying operating system, 16797on the exact target in use, this information can be used to determine 16798the required metrics. 16799 16800 16801@itemize * 16802 16803@item 16804"The declarations of @cite{Any_Priority} and 16805@cite{Priority}. See D.1(11)." 16806@end itemize 16807 16808See declarations in file @code{system.ads}. 16809 16810 16811@itemize * 16812 16813@item 16814"Implementation-defined execution resources. See D.1(15)." 16815@end itemize 16816 16817There are no implementation-defined execution resources. 16818 16819 16820@itemize * 16821 16822@item 16823"Whether, on a multiprocessor, a task that is waiting for 16824access to a protected object keeps its processor busy. See D.2.1(3)." 16825@end itemize 16826 16827On a multi-processor, a task that is waiting for access to a protected 16828object does not keep its processor busy. 16829 16830 16831@itemize * 16832 16833@item 16834"The affect of implementation defined execution resources 16835on task dispatching. See D.2.1(9)." 16836@end itemize 16837 16838Tasks map to threads in the threads package used by GNAT. Where possible 16839and appropriate, these threads correspond to native threads of the 16840underlying operating system. 16841 16842 16843@itemize * 16844 16845@item 16846"Implementation-defined @cite{policy_identifiers} allowed 16847in a pragma @cite{Task_Dispatching_Policy}. See D.2.2(3)." 16848@end itemize 16849 16850There are no implementation-defined policy-identifiers allowed in this 16851pragma. 16852 16853 16854@itemize * 16855 16856@item 16857"Implementation-defined aspects of priority inversion. See 16858D.2.2(16)." 16859@end itemize 16860 16861Execution of a task cannot be preempted by the implementation processing 16862of delay expirations for lower priority tasks. 16863 16864 16865@itemize * 16866 16867@item 16868"Implementation-defined task dispatching. See D.2.2(18)." 16869@end itemize 16870 16871The policy is the same as that of the underlying threads implementation. 16872 16873 16874@itemize * 16875 16876@item 16877"Implementation-defined @cite{policy_identifiers} allowed 16878in a pragma @cite{Locking_Policy}. See D.3(4)." 16879@end itemize 16880 16881The two implementation defined policies permitted in GNAT are 16882@cite{Inheritance_Locking} and @cite{Conccurent_Readers_Locking}. On 16883targets that support the @cite{Inheritance_Locking} policy, locking is 16884implemented by inheritance, i.e., the task owning the lock operates 16885at a priority equal to the highest priority of any task currently 16886requesting the lock. On targets that support the 16887@cite{Conccurent_Readers_Locking} policy, locking is implemented with a 16888read/write lock allowing multiple propected object functions to enter 16889concurrently. 16890 16891 16892@itemize * 16893 16894@item 16895"Default ceiling priorities. See D.3(10)." 16896@end itemize 16897 16898The ceiling priority of protected objects of the type 16899@cite{System.Interrupt_Priority'Last} as described in the Ada 16900Reference Manual D.3(10), 16901 16902 16903@itemize * 16904 16905@item 16906"The ceiling of any protected object used internally by 16907the implementation. See D.3(16)." 16908@end itemize 16909 16910The ceiling priority of internal protected objects is 16911@cite{System.Priority'Last}. 16912 16913 16914@itemize * 16915 16916@item 16917"Implementation-defined queuing policies. See D.4(1)." 16918@end itemize 16919 16920There are no implementation-defined queuing policies. 16921 16922 16923@itemize * 16924 16925@item 16926"On a multiprocessor, any conditions that cause the 16927completion of an aborted construct to be delayed later than what is 16928specified for a single processor. See D.6(3)." 16929@end itemize 16930 16931The semantics for abort on a multi-processor is the same as on a single 16932processor, there are no further delays. 16933 16934 16935@itemize * 16936 16937@item 16938"Any operations that implicitly require heap storage 16939allocation. See D.7(8)." 16940@end itemize 16941 16942The only operation that implicitly requires heap storage allocation is 16943task creation. 16944 16945 16946@itemize * 16947 16948@item 16949"What happens when a task terminates in the presence of 16950pragma @cite{No_Task_Termination}. See D.7(15)." 16951@end itemize 16952 16953Execution is erroneous in that case. 16954 16955 16956@itemize * 16957 16958@item 16959"Implementation-defined aspects of pragma 16960@cite{Restrictions}. See D.7(20)." 16961@end itemize 16962 16963There are no such implementation-defined aspects. 16964 16965 16966@itemize * 16967 16968@item 16969"Implementation-defined aspects of package 16970@cite{Real_Time}. See D.8(17)." 16971@end itemize 16972 16973There are no implementation defined aspects of package @cite{Real_Time}. 16974 16975 16976@itemize * 16977 16978@item 16979"Implementation-defined aspects of 16980@cite{delay_statements}. See D.9(8)." 16981@end itemize 16982 16983Any difference greater than one microsecond will cause the task to be 16984delayed (see D.9(7)). 16985 16986 16987@itemize * 16988 16989@item 16990"The upper bound on the duration of interrupt blocking 16991caused by the implementation. See D.12(5)." 16992@end itemize 16993 16994The upper bound is determined by the underlying operating system. In 16995no cases is it more than 10 milliseconds. 16996 16997 16998@itemize * 16999 17000@item 17001"The means for creating and executing distributed 17002programs. See E(5)." 17003@end itemize 17004 17005The GLADE package provides a utility GNATDIST for creating and executing 17006distributed programs. See the GLADE reference manual for further details. 17007 17008 17009@itemize * 17010 17011@item 17012"Any events that can result in a partition becoming 17013inaccessible. See E.1(7)." 17014@end itemize 17015 17016See the GLADE reference manual for full details on such events. 17017 17018 17019@itemize * 17020 17021@item 17022"The scheduling policies, treatment of priorities, and 17023management of shared resources between partitions in certain cases. See 17024E.1(11)." 17025@end itemize 17026 17027See the GLADE reference manual for full details on these aspects of 17028multi-partition execution. 17029 17030 17031@itemize * 17032 17033@item 17034"Events that cause the version of a compilation unit to 17035change. See E.3(5)." 17036@end itemize 17037 17038Editing the source file of a compilation unit, or the source files of 17039any units on which it is dependent in a significant way cause the version 17040to change. No other actions cause the version number to change. All changes 17041are significant except those which affect only layout, capitalization or 17042comments. 17043 17044 17045@itemize * 17046 17047@item 17048"Whether the execution of the remote subprogram is 17049immediately aborted as a result of cancellation. See E.4(13)." 17050@end itemize 17051 17052See the GLADE reference manual for details on the effect of abort in 17053a distributed application. 17054 17055 17056@itemize * 17057 17058@item 17059"Implementation-defined aspects of the PCS. See E.5(25)." 17060@end itemize 17061 17062See the GLADE reference manual for a full description of all implementation 17063defined aspects of the PCS. 17064 17065 17066@itemize * 17067 17068@item 17069"Implementation-defined interfaces in the PCS. See 17070E.5(26)." 17071@end itemize 17072 17073See the GLADE reference manual for a full description of all 17074implementation defined interfaces. 17075 17076 17077@itemize * 17078 17079@item 17080"The values of named numbers in the package 17081@cite{Decimal}. See F.2(7)." 17082@end itemize 17083 17084 17085@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17086@headitem 17087 17088Named Number 17089 17090@tab 17091 17092Value 17093 17094@item 17095 17096@emph{Max_Scale} 17097 17098@tab 17099 17100+18 17101 17102@item 17103 17104@emph{Min_Scale} 17105 17106@tab 17107 17108-18 17109 17110@item 17111 17112@emph{Min_Delta} 17113 17114@tab 17115 171161.0E-18 17117 17118@item 17119 17120@emph{Max_Delta} 17121 17122@tab 17123 171241.0E+18 17125 17126@item 17127 17128@emph{Max_Decimal_Digits} 17129 17130@tab 17131 1713218 17133 17134@end multitable 17135 17136 17137 17138@itemize * 17139 17140@item 17141"The value of @cite{Max_Picture_Length} in the package 17142@cite{Text_IO.Editing}. See F.3.3(16)." 17143@end itemize 17144 1714564 17146 17147 17148@itemize * 17149 17150@item 17151"The value of @cite{Max_Picture_Length} in the package 17152@cite{Wide_Text_IO.Editing}. See F.3.4(5)." 17153@end itemize 17154 1715564 17156 17157 17158@itemize * 17159 17160@item 17161"The accuracy actually achieved by the complex elementary 17162functions and by other complex arithmetic operations. See G.1(1)." 17163@end itemize 17164 17165Standard library functions are used for the complex arithmetic 17166operations. Only fast math mode is currently supported. 17167 17168 17169@itemize * 17170 17171@item 17172"The sign of a zero result (or a component thereof) from 17173any operator or function in @cite{Numerics.Generic_Complex_Types}, when 17174@cite{Real'Signed_Zeros} is True. See G.1.1(53)." 17175@end itemize 17176 17177The signs of zero values are as recommended by the relevant 17178implementation advice. 17179 17180 17181@itemize * 17182 17183@item 17184"The sign of a zero result (or a component thereof) from 17185any operator or function in 17186@cite{Numerics.Generic_Complex_Elementary_Functions}, when 17187@cite{Real'Signed_Zeros} is @cite{True}. See G.1.2(45)." 17188@end itemize 17189 17190The signs of zero values are as recommended by the relevant 17191implementation advice. 17192 17193 17194@itemize * 17195 17196@item 17197"Whether the strict mode or the relaxed mode is the 17198default. See G.2(2)." 17199@end itemize 17200 17201The strict mode is the default. There is no separate relaxed mode. GNAT 17202provides a highly efficient implementation of strict mode. 17203 17204 17205@itemize * 17206 17207@item 17208"The result interval in certain cases of fixed-to-float 17209conversion. See G.2.1(10)." 17210@end itemize 17211 17212For cases where the result interval is implementation dependent, the 17213accuracy is that provided by performing all operations in 64-bit IEEE 17214floating-point format. 17215 17216 17217@itemize * 17218 17219@item 17220"The result of a floating point arithmetic operation in 17221overflow situations, when the @cite{Machine_Overflows} attribute of the 17222result type is @cite{False}. See G.2.1(13)." 17223@end itemize 17224 17225Infinite and NaN values are produced as dictated by the IEEE 17226floating-point standard. 17227Note that on machines that are not fully compliant with the IEEE 17228floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 17229must be used for achieving IEEE conforming behavior (although at the cost 17230of a significant performance penalty), so infinite and NaN values are 17231properly generated. 17232 17233 17234@itemize * 17235 17236@item 17237"The result interval for division (or exponentiation by a 17238negative exponent), when the floating point hardware implements division 17239as multiplication by a reciprocal. See G.2.1(16)." 17240@end itemize 17241 17242Not relevant, division is IEEE exact. 17243 17244 17245@itemize * 17246 17247@item 17248"The definition of close result set, which determines the 17249accuracy of certain fixed point multiplications and divisions. See 17250G.2.3(5)." 17251@end itemize 17252 17253Operations in the close result set are performed using IEEE long format 17254floating-point arithmetic. The input operands are converted to 17255floating-point, the operation is done in floating-point, and the result 17256is converted to the target type. 17257 17258 17259@itemize * 17260 17261@item 17262"Conditions on a @cite{universal_real} operand of a fixed 17263point multiplication or division for which the result shall be in the 17264perfect result set. See G.2.3(22)." 17265@end itemize 17266 17267The result is only defined to be in the perfect result set if the result 17268can be computed by a single scaling operation involving a scale factor 17269representable in 64-bits. 17270 17271 17272@itemize * 17273 17274@item 17275"The result of a fixed point arithmetic operation in 17276overflow situations, when the @cite{Machine_Overflows} attribute of the 17277result type is @cite{False}. See G.2.3(27)." 17278@end itemize 17279 17280Not relevant, @cite{Machine_Overflows} is @cite{True} for fixed-point 17281types. 17282 17283 17284@itemize * 17285 17286@item 17287"The result of an elementary function reference in 17288overflow situations, when the @cite{Machine_Overflows} attribute of the 17289result type is @cite{False}. See G.2.4(4)." 17290@end itemize 17291 17292IEEE infinite and Nan values are produced as appropriate. 17293 17294 17295@itemize * 17296 17297@item 17298"The value of the angle threshold, within which certain 17299elementary functions, complex arithmetic operations, and complex 17300elementary functions yield results conforming to a maximum relative 17301error bound. See G.2.4(10)." 17302@end itemize 17303 17304Information on this subject is not yet available. 17305 17306 17307@itemize * 17308 17309@item 17310"The accuracy of certain elementary functions for 17311parameters beyond the angle threshold. See G.2.4(10)." 17312@end itemize 17313 17314Information on this subject is not yet available. 17315 17316 17317@itemize * 17318 17319@item 17320"The result of a complex arithmetic operation or complex 17321elementary function reference in overflow situations, when the 17322@cite{Machine_Overflows} attribute of the corresponding real type is 17323@cite{False}. See G.2.6(5)." 17324@end itemize 17325 17326IEEE infinite and Nan values are produced as appropriate. 17327 17328 17329@itemize * 17330 17331@item 17332"The accuracy of certain complex arithmetic operations and 17333certain complex elementary functions for parameters (or components 17334thereof) beyond the angle threshold. See G.2.6(8)." 17335@end itemize 17336 17337Information on those subjects is not yet available. 17338 17339 17340@itemize * 17341 17342@item 17343"Information regarding bounded errors and erroneous 17344execution. See H.2(1)." 17345@end itemize 17346 17347Information on this subject is not yet available. 17348 17349 17350@itemize * 17351 17352@item 17353"Implementation-defined aspects of pragma 17354@cite{Inspection_Point}. See H.3.2(8)." 17355@end itemize 17356 17357Pragma @cite{Inspection_Point} ensures that the variable is live and can 17358be examined by the debugger at the inspection point. 17359 17360 17361@itemize * 17362 17363@item 17364"Implementation-defined aspects of pragma 17365@cite{Restrictions}. See H.4(25)." 17366@end itemize 17367 17368There are no implementation-defined aspects of pragma @cite{Restrictions}. The 17369use of pragma @cite{Restrictions [No_Exceptions]} has no effect on the 17370generated code. Checks must suppressed by use of pragma @cite{Suppress}. 17371 17372 17373@itemize * 17374 17375@item 17376"Any restrictions on pragma @cite{Restrictions}. See 17377H.4(27)." 17378@end itemize 17379 17380There are no restrictions on pragma @cite{Restrictions}. 17381 17382@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 17383@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{211}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{212} 17384@chapter Intrinsic Subprograms 17385 17386 17387@geindex Intrinsic Subprograms 17388 17389GNAT allows a user application program to write the declaration: 17390 17391@example 17392pragma Import (Intrinsic, name); 17393@end example 17394 17395providing that the name corresponds to one of the implemented intrinsic 17396subprograms in GNAT, and that the parameter profile of the referenced 17397subprogram meets the requirements. This chapter describes the set of 17398implemented intrinsic subprograms, and the requirements on parameter profiles. 17399Note that no body is supplied; as with other uses of pragma Import, the 17400body is supplied elsewhere (in this case by the compiler itself). Note 17401that any use of this feature is potentially non-portable, since the 17402Ada standard does not require Ada compilers to implement this feature. 17403 17404@menu 17405* Intrinsic Operators:: 17406* Compilation_Date:: 17407* Compilation_Time:: 17408* Enclosing_Entity:: 17409* Exception_Information:: 17410* Exception_Message:: 17411* Exception_Name:: 17412* File:: 17413* Line:: 17414* Shifts and Rotates:: 17415* Source_Location:: 17416 17417@end menu 17418 17419@node Intrinsic Operators,Compilation_Date,,Intrinsic Subprograms 17420@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{213}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{214} 17421@section Intrinsic Operators 17422 17423 17424@geindex Intrinsic operator 17425 17426All the predefined numeric operators in package Standard 17427in @cite{pragma Import (Intrinsic@comma{}..)} 17428declarations. In the binary operator case, the operands must have the same 17429size. The operand or operands must also be appropriate for 17430the operator. For example, for addition, the operands must 17431both be floating-point or both be fixed-point, and the 17432right operand for @cite{"**"} must have a root type of 17433@cite{Standard.Integer'Base}. 17434You can use an intrinsic operator declaration as in the following example: 17435 17436@example 17437type Int1 is new Integer; 17438type Int2 is new Integer; 17439 17440function "+" (X1 : Int1; X2 : Int2) return Int1; 17441function "+" (X1 : Int1; X2 : Int2) return Int2; 17442pragma Import (Intrinsic, "+"); 17443@end example 17444 17445This declaration would permit 'mixed mode' arithmetic on items 17446of the differing types @cite{Int1} and @cite{Int2}. 17447It is also possible to specify such operators for private types, if the 17448full views are appropriate arithmetic types. 17449 17450@node Compilation_Date,Compilation_Time,Intrinsic Operators,Intrinsic Subprograms 17451@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{215}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{216} 17452@section Compilation_Date 17453 17454 17455@geindex Compilation_Date 17456 17457This intrinsic subprogram is used in the implementation of the 17458library package @cite{GNAT.Source_Info}. The only useful use of the 17459intrinsic import in this case is the one in this unit, so an 17460application program should simply call the function 17461@cite{GNAT.Source_Info.Compilation_Date} to obtain the date of 17462the current compilation (in local time format MMM DD YYYY). 17463 17464@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 17465@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{217}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{218} 17466@section Compilation_Time 17467 17468 17469@geindex Compilation_Time 17470 17471This intrinsic subprogram is used in the implementation of the 17472library package @cite{GNAT.Source_Info}. The only useful use of the 17473intrinsic import in this case is the one in this unit, so an 17474application program should simply call the function 17475@cite{GNAT.Source_Info.Compilation_Time} to obtain the time of 17476the current compilation (in local time format HH:MM:SS). 17477 17478@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 17479@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{219}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{21a} 17480@section Enclosing_Entity 17481 17482 17483@geindex Enclosing_Entity 17484 17485This intrinsic subprogram is used in the implementation of the 17486library package @cite{GNAT.Source_Info}. The only useful use of the 17487intrinsic import in this case is the one in this unit, so an 17488application program should simply call the function 17489@cite{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 17490the current subprogram, package, task, entry, or protected subprogram. 17491 17492@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 17493@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{21b}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{21c} 17494@section Exception_Information 17495 17496 17497@geindex Exception_Information' 17498 17499This intrinsic subprogram is used in the implementation of the 17500library package @cite{GNAT.Current_Exception}. The only useful 17501use of the intrinsic import in this case is the one in this unit, 17502so an application program should simply call the function 17503@cite{GNAT.Current_Exception.Exception_Information} to obtain 17504the exception information associated with the current exception. 17505 17506@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 17507@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{21d}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{21e} 17508@section Exception_Message 17509 17510 17511@geindex Exception_Message 17512 17513This intrinsic subprogram is used in the implementation of the 17514library package @cite{GNAT.Current_Exception}. The only useful 17515use of the intrinsic import in this case is the one in this unit, 17516so an application program should simply call the function 17517@cite{GNAT.Current_Exception.Exception_Message} to obtain 17518the message associated with the current exception. 17519 17520@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 17521@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{21f}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{220} 17522@section Exception_Name 17523 17524 17525@geindex Exception_Name 17526 17527This intrinsic subprogram is used in the implementation of the 17528library package @cite{GNAT.Current_Exception}. The only useful 17529use of the intrinsic import in this case is the one in this unit, 17530so an application program should simply call the function 17531@cite{GNAT.Current_Exception.Exception_Name} to obtain 17532the name of the current exception. 17533 17534@node File,Line,Exception_Name,Intrinsic Subprograms 17535@anchor{gnat_rm/intrinsic_subprograms file}@anchor{221}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{222} 17536@section File 17537 17538 17539@geindex File 17540 17541This intrinsic subprogram is used in the implementation of the 17542library package @cite{GNAT.Source_Info}. The only useful use of the 17543intrinsic import in this case is the one in this unit, so an 17544application program should simply call the function 17545@cite{GNAT.Source_Info.File} to obtain the name of the current 17546file. 17547 17548@node Line,Shifts and Rotates,File,Intrinsic Subprograms 17549@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{223}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{224} 17550@section Line 17551 17552 17553@geindex Line 17554 17555This intrinsic subprogram is used in the implementation of the 17556library package @cite{GNAT.Source_Info}. The only useful use of the 17557intrinsic import in this case is the one in this unit, so an 17558application program should simply call the function 17559@cite{GNAT.Source_Info.Line} to obtain the number of the current 17560source line. 17561 17562@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 17563@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{225}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{226} 17564@section Shifts and Rotates 17565 17566 17567@geindex Shift_Left 17568 17569@geindex Shift_Right 17570 17571@geindex Shift_Right_Arithmetic 17572 17573@geindex Rotate_Left 17574 17575@geindex Rotate_Right 17576 17577In standard Ada, the shift and rotate functions are available only 17578for the predefined modular types in package @cite{Interfaces}. However, in 17579GNAT it is possible to define these functions for any integer 17580type (signed or modular), as in this example: 17581 17582@example 17583function Shift_Left 17584 (Value : T; 17585 Amount : Natural) return T; 17586@end example 17587 17588The function name must be one of 17589Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 17590Rotate_Right. T must be an integer type. T'Size must be 175918, 16, 32 or 64 bits; if T is modular, the modulus 17592must be 2**8, 2**16, 2**32 or 2**64. 17593The result type must be the same as the type of @cite{Value}. 17594The shift amount must be Natural. 17595The formal parameter names can be anything. 17596 17597A more convenient way of providing these shift operators is to use 17598the Provide_Shift_Operators pragma, which provides the function declarations 17599and corresponding pragma Import's for all five shift functions. 17600 17601@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 17602@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{227}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{228} 17603@section Source_Location 17604 17605 17606@geindex Source_Location 17607 17608This intrinsic subprogram is used in the implementation of the 17609library routine @cite{GNAT.Source_Info}. The only useful use of the 17610intrinsic import in this case is the one in this unit, so an 17611application program should simply call the function 17612@cite{GNAT.Source_Info.Source_Location} to obtain the current 17613source file location. 17614 17615@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 17616@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{229}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{22a} 17617@chapter Representation Clauses and Pragmas 17618 17619 17620@geindex Representation Clauses 17621 17622@geindex Representation Clause 17623 17624@geindex Representation Pragma 17625 17626@geindex Pragma 17627@geindex representation 17628 17629This section describes the representation clauses accepted by GNAT, and 17630their effect on the representation of corresponding data objects. 17631 17632GNAT fully implements Annex C (Systems Programming). This means that all 17633the implementation advice sections in chapter 13 are fully implemented. 17634However, these sections only require a minimal level of support for 17635representation clauses. GNAT provides much more extensive capabilities, 17636and this section describes the additional capabilities provided. 17637 17638@menu 17639* Alignment Clauses:: 17640* Size Clauses:: 17641* Storage_Size Clauses:: 17642* Size of Variant Record Objects:: 17643* Biased Representation:: 17644* Value_Size and Object_Size Clauses:: 17645* Component_Size Clauses:: 17646* Bit_Order Clauses:: 17647* Effect of Bit_Order on Byte Ordering:: 17648* Pragma Pack for Arrays:: 17649* Pragma Pack for Records:: 17650* Record Representation Clauses:: 17651* Handling of Records with Holes:: 17652* Enumeration Clauses:: 17653* Address Clauses:: 17654* Use of Address Clauses for Memory-Mapped I/O:: 17655* Effect of Convention on Representation:: 17656* Conventions and Anonymous Access Types:: 17657* Determining the Representations chosen by GNAT:: 17658 17659@end menu 17660 17661@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 17662@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{22b}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{22c} 17663@section Alignment Clauses 17664 17665 17666@geindex Alignment Clause 17667 17668GNAT requires that all alignment clauses specify a power of 2, and all 17669default alignments are always a power of 2. The default alignment 17670values are as follows: 17671 17672 17673@itemize * 17674 17675@item 17676@emph{Primitive Types}. 17677 17678For primitive types, the alignment is the minimum of the actual size of 17679objects of the type divided by @cite{Storage_Unit}, 17680and the maximum alignment supported by the target. 17681(This maximum alignment is given by the GNAT-specific attribute 17682@cite{Standard'Maximum_Alignment}; see @ref{149,,Attribute Maximum_Alignment}.) 17683 17684@geindex Maximum_Alignment attribute 17685 17686For example, for type @cite{Long_Float}, the object size is 8 bytes, and the 17687default alignment will be 8 on any target that supports alignments 17688this large, but on some targets, the maximum alignment may be smaller 17689than 8, in which case objects of type @cite{Long_Float} will be maximally 17690aligned. 17691 17692@item 17693@emph{Arrays}. 17694 17695For arrays, the alignment is equal to the alignment of the component type 17696for the normal case where no packing or component size is given. If the 17697array is packed, and the packing is effective (see separate section on 17698packed arrays), then the alignment will be one for long packed arrays, 17699or arrays whose length is not known at compile time. For short packed 17700arrays, which are handled internally as modular types, the alignment 17701will be as described for primitive types, e.g., a packed array of length 1770231 bits will have an object size of four bytes, and an alignment of 4. 17703 17704@item 17705@emph{Records}. 17706 17707For the normal non-packed case, the alignment of a record is equal to 17708the maximum alignment of any of its components. For tagged records, this 17709includes the implicit access type used for the tag. If a pragma @cite{Pack} 17710is used and all components are packable (see separate section on pragma 17711@cite{Pack}), then the resulting alignment is 1, unless the layout of the 17712record makes it profitable to increase it. 17713 17714A special case is when: 17715 17716 17717@itemize * 17718 17719@item 17720the size of the record is given explicitly, or a 17721full record representation clause is given, and 17722 17723@item 17724the size of the record is 2, 4, or 8 bytes. 17725@end itemize 17726 17727In this case, an alignment is chosen to match the 17728size of the record. For example, if we have: 17729 17730@example 17731type Small is record 17732 A, B : Character; 17733end record; 17734for Small'Size use 16; 17735@end example 17736 17737then the default alignment of the record type @cite{Small} is 2, not 1. This 17738leads to more efficient code when the record is treated as a unit, and also 17739allows the type to specified as @cite{Atomic} on architectures requiring 17740strict alignment. 17741@end itemize 17742 17743An alignment clause may specify a larger alignment than the default value 17744up to some maximum value dependent on the target (obtainable by using the 17745attribute reference @cite{Standard'Maximum_Alignment}). It may also specify 17746a smaller alignment than the default value for enumeration, integer and 17747fixed point types, as well as for record types, for example 17748 17749@example 17750type V is record 17751 A : Integer; 17752end record; 17753 17754for V'alignment use 1; 17755@end example 17756 17757@geindex Alignment 17758@geindex default 17759 17760The default alignment for the type @cite{V} is 4, as a result of the 17761Integer field in the record, but it is permissible, as shown, to 17762override the default alignment of the record with a smaller value. 17763 17764@geindex Alignment 17765@geindex subtypes 17766 17767Note that according to the Ada standard, an alignment clause applies only 17768to the first named subtype. If additional subtypes are declared, then the 17769compiler is allowed to choose any alignment it likes, and there is no way 17770to control this choice. Consider: 17771 17772@example 17773type R is range 1 .. 10_000; 17774for R'Alignment use 1; 17775subtype RS is R range 1 .. 1000; 17776@end example 17777 17778The alignment clause specifies an alignment of 1 for the first named subtype 17779@cite{R} but this does not necessarily apply to @cite{RS}. When writing 17780portable Ada code, you should avoid writing code that explicitly or 17781implicitly relies on the alignment of such subtypes. 17782 17783For the GNAT compiler, if an explicit alignment clause is given, this 17784value is also used for any subsequent subtypes. So for GNAT, in the 17785above example, you can count on the alignment of @cite{RS} being 1. But this 17786assumption is non-portable, and other compilers may choose different 17787alignments for the subtype @cite{RS}. 17788 17789@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 17790@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{22d}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{22e} 17791@section Size Clauses 17792 17793 17794@geindex Size Clause 17795 17796The default size for a type @cite{T} is obtainable through the 17797language-defined attribute @cite{T'Size} and also through the 17798equivalent GNAT-defined attribute @cite{T'Value_Size}. 17799For objects of type @cite{T}, GNAT will generally increase the type size 17800so that the object size (obtainable through the GNAT-defined attribute 17801@cite{T'Object_Size}) 17802is a multiple of @cite{T'Alignment * Storage_Unit}. 17803 17804For example: 17805 17806@example 17807type Smallint is range 1 .. 6; 17808 17809type Rec is record 17810 Y1 : integer; 17811 Y2 : boolean; 17812end record; 17813@end example 17814 17815In this example, @cite{Smallint'Size} = @cite{Smallint'Value_Size} = 3, 17816as specified by the RM rules, 17817but objects of this type will have a size of 8 17818(@cite{Smallint'Object_Size} = 8), 17819since objects by default occupy an integral number 17820of storage units. On some targets, notably older 17821versions of the Digital Alpha, the size of stand 17822alone objects of this type may be 32, reflecting 17823the inability of the hardware to do byte load/stores. 17824 17825Similarly, the size of type @cite{Rec} is 40 bits 17826(@cite{Rec'Size} = @cite{Rec'Value_Size} = 40), but 17827the alignment is 4, so objects of this type will have 17828their size increased to 64 bits so that it is a multiple 17829of the alignment (in bits). This decision is 17830in accordance with the specific Implementation Advice in RM 13.3(43): 17831 17832@quotation 17833 17834"A @cite{Size} clause should be supported for an object if the specified 17835@cite{Size} is at least as large as its subtype's @cite{Size}, and corresponds 17836to a size in storage elements that is a multiple of the object's 17837@cite{Alignment} (if the @cite{Alignment} is nonzero)." 17838@end quotation 17839 17840An explicit size clause may be used to override the default size by 17841increasing it. For example, if we have: 17842 17843@example 17844type My_Boolean is new Boolean; 17845for My_Boolean'Size use 32; 17846@end example 17847 17848then values of this type will always be 32 bits long. In the case of 17849discrete types, the size can be increased up to 64 bits, with the effect 17850that the entire specified field is used to hold the value, sign- or 17851zero-extended as appropriate. If more than 64 bits is specified, then 17852padding space is allocated after the value, and a warning is issued that 17853there are unused bits. 17854 17855Similarly the size of records and arrays may be increased, and the effect 17856is to add padding bits after the value. This also causes a warning message 17857to be generated. 17858 17859The largest Size value permitted in GNAT is 2**31-1. Since this is a 17860Size in bits, this corresponds to an object of size 256 megabytes (minus 17861one). This limitation is true on all targets. The reason for this 17862limitation is that it improves the quality of the code in many cases 17863if it is known that a Size value can be accommodated in an object of 17864type Integer. 17865 17866@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 17867@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{22f}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{230} 17868@section Storage_Size Clauses 17869 17870 17871@geindex Storage_Size Clause 17872 17873For tasks, the @cite{Storage_Size} clause specifies the amount of space 17874to be allocated for the task stack. This cannot be extended, and if the 17875stack is exhausted, then @cite{Storage_Error} will be raised (if stack 17876checking is enabled). Use a @cite{Storage_Size} attribute definition clause, 17877or a @cite{Storage_Size} pragma in the task definition to set the 17878appropriate required size. A useful technique is to include in every 17879task definition a pragma of the form: 17880 17881@example 17882pragma Storage_Size (Default_Stack_Size); 17883@end example 17884 17885Then @cite{Default_Stack_Size} can be defined in a global package, and 17886modified as required. Any tasks requiring stack sizes different from the 17887default can have an appropriate alternative reference in the pragma. 17888 17889You can also use the @emph{-d} binder switch to modify the default stack 17890size. 17891 17892For access types, the @cite{Storage_Size} clause specifies the maximum 17893space available for allocation of objects of the type. If this space is 17894exceeded then @cite{Storage_Error} will be raised by an allocation attempt. 17895In the case where the access type is declared local to a subprogram, the 17896use of a @cite{Storage_Size} clause triggers automatic use of a special 17897predefined storage pool (@cite{System.Pool_Size}) that ensures that all 17898space for the pool is automatically reclaimed on exit from the scope in 17899which the type is declared. 17900 17901A special case recognized by the compiler is the specification of a 17902@cite{Storage_Size} of zero for an access type. This means that no 17903items can be allocated from the pool, and this is recognized at compile 17904time, and all the overhead normally associated with maintaining a fixed 17905size storage pool is eliminated. Consider the following example: 17906 17907@example 17908procedure p is 17909 type R is array (Natural) of Character; 17910 type P is access all R; 17911 for P'Storage_Size use 0; 17912 -- Above access type intended only for interfacing purposes 17913 17914 y : P; 17915 17916 procedure g (m : P); 17917 pragma Import (C, g); 17918 17919 -- ... 17920 17921begin 17922 -- ... 17923 y := new R; 17924end; 17925@end example 17926 17927As indicated in this example, these dummy storage pools are often useful in 17928connection with interfacing where no object will ever be allocated. If you 17929compile the above example, you get the warning: 17930 17931@example 17932p.adb:16:09: warning: allocation from empty storage pool 17933p.adb:16:09: warning: Storage_Error will be raised at run time 17934@end example 17935 17936Of course in practice, there will not be any explicit allocators in the 17937case of such an access declaration. 17938 17939@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 17940@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{231}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{232} 17941@section Size of Variant Record Objects 17942 17943 17944@geindex Size 17945@geindex variant record objects 17946 17947@geindex Variant record objects 17948@geindex size 17949 17950In the case of variant record objects, there is a question whether Size gives 17951information about a particular variant, or the maximum size required 17952for any variant. Consider the following program 17953 17954@example 17955with Text_IO; use Text_IO; 17956procedure q is 17957 type R1 (A : Boolean := False) is record 17958 case A is 17959 when True => X : Character; 17960 when False => null; 17961 end case; 17962 end record; 17963 17964 V1 : R1 (False); 17965 V2 : R1; 17966 17967begin 17968 Put_Line (Integer'Image (V1'Size)); 17969 Put_Line (Integer'Image (V2'Size)); 17970end q; 17971@end example 17972 17973Here we are dealing with a variant record, where the True variant 17974requires 16 bits, and the False variant requires 8 bits. 17975In the above example, both V1 and V2 contain the False variant, 17976which is only 8 bits long. However, the result of running the 17977program is: 17978 17979@example 179808 1798116 17982@end example 17983 17984The reason for the difference here is that the discriminant value of 17985V1 is fixed, and will always be False. It is not possible to assign 17986a True variant value to V1, therefore 8 bits is sufficient. On the 17987other hand, in the case of V2, the initial discriminant value is 17988False (from the default), but it is possible to assign a True 17989variant value to V2, therefore 16 bits must be allocated for V2 17990in the general case, even fewer bits may be needed at any particular 17991point during the program execution. 17992 17993As can be seen from the output of this program, the @cite{'Size} 17994attribute applied to such an object in GNAT gives the actual allocated 17995size of the variable, which is the largest size of any of the variants. 17996The Ada Reference Manual is not completely clear on what choice should 17997be made here, but the GNAT behavior seems most consistent with the 17998language in the RM. 17999 18000In some cases, it may be desirable to obtain the size of the current 18001variant, rather than the size of the largest variant. This can be 18002achieved in GNAT by making use of the fact that in the case of a 18003subprogram parameter, GNAT does indeed return the size of the current 18004variant (because a subprogram has no way of knowing how much space 18005is actually allocated for the actual). 18006 18007Consider the following modified version of the above program: 18008 18009@example 18010with Text_IO; use Text_IO; 18011procedure q is 18012 type R1 (A : Boolean := False) is record 18013 case A is 18014 when True => X : Character; 18015 when False => null; 18016 end case; 18017 end record; 18018 18019 V2 : R1; 18020 18021 function Size (V : R1) return Integer is 18022 begin 18023 return V'Size; 18024 end Size; 18025 18026begin 18027 Put_Line (Integer'Image (V2'Size)); 18028 Put_Line (Integer'Image (Size (V2))); 18029 V2 := (True, 'x'); 18030 Put_Line (Integer'Image (V2'Size)); 18031 Put_Line (Integer'Image (Size (V2))); 18032end q; 18033@end example 18034 18035The output from this program is 18036 18037@example 1803816 180398 1804016 1804116 18042@end example 18043 18044Here we see that while the @cite{'Size} attribute always returns 18045the maximum size, regardless of the current variant value, the 18046@cite{Size} function does indeed return the size of the current 18047variant value. 18048 18049@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18050@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{233}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{234} 18051@section Biased Representation 18052 18053 18054@geindex Size for biased representation 18055 18056@geindex Biased representation 18057 18058In the case of scalars with a range starting at other than zero, it is 18059possible in some cases to specify a size smaller than the default minimum 18060value, and in such cases, GNAT uses an unsigned biased representation, 18061in which zero is used to represent the lower bound, and successive values 18062represent successive values of the type. 18063 18064For example, suppose we have the declaration: 18065 18066@example 18067type Small is range -7 .. -4; 18068for Small'Size use 2; 18069@end example 18070 18071Although the default size of type @cite{Small} is 4, the @cite{Size} 18072clause is accepted by GNAT and results in the following representation 18073scheme: 18074 18075@example 18076-7 is represented as 2#00# 18077-6 is represented as 2#01# 18078-5 is represented as 2#10# 18079-4 is represented as 2#11# 18080@end example 18081 18082Biased representation is only used if the specified @cite{Size} clause 18083cannot be accepted in any other manner. These reduced sizes that force 18084biased representation can be used for all discrete types except for 18085enumeration types for which a representation clause is given. 18086 18087@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18088@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{235}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{236} 18089@section Value_Size and Object_Size Clauses 18090 18091 18092@geindex Value_Size 18093 18094@geindex Object_Size 18095 18096@geindex Size 18097@geindex of objects 18098 18099In Ada 95 and Ada 2005, @cite{T'Size} for a type @cite{T} is the minimum 18100number of bits required to hold values of type @cite{T}. 18101Although this interpretation was allowed in Ada 83, it was not required, 18102and this requirement in practice can cause some significant difficulties. 18103For example, in most Ada 83 compilers, @cite{Natural'Size} was 32. 18104However, in Ada 95 and Ada 2005, 18105@cite{Natural'Size} is 18106typically 31. This means that code may change in behavior when moving 18107from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18108 18109@example 18110type Rec is record; 18111 A : Natural; 18112 B : Natural; 18113end record; 18114 18115for Rec use record 18116 at 0 range 0 .. Natural'Size - 1; 18117 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18118end record; 18119@end example 18120 18121In the above code, since the typical size of @cite{Natural} objects 18122is 32 bits and @cite{Natural'Size} is 31, the above code can cause 18123unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18124there are cases where the fact that the object size can exceed the 18125size of the type causes surprises. 18126 18127To help get around this problem GNAT provides two implementation 18128defined attributes, @cite{Value_Size} and @cite{Object_Size}. When 18129applied to a type, these attributes yield the size of the type 18130(corresponding to the RM defined size attribute), and the size of 18131objects of the type respectively. 18132 18133The @cite{Object_Size} is used for determining the default size of 18134objects and components. This size value can be referred to using the 18135@cite{Object_Size} attribute. The phrase 'is used' here means that it is 18136the basis of the determination of the size. The backend is free to 18137pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18138character might be stored in 32 bits on a machine with no efficient 18139byte access instructions such as the Alpha. 18140 18141The default rules for the value of @cite{Object_Size} for 18142discrete types are as follows: 18143 18144 18145@itemize * 18146 18147@item 18148The @cite{Object_Size} for base subtypes reflect the natural hardware 18149size in bits (run the compiler with @emph{-gnatS} to find those values 18150for numeric types). Enumeration types and fixed-point base subtypes have 181518, 16, 32 or 64 bits for this size, depending on the range of values 18152to be stored. 18153 18154@item 18155The @cite{Object_Size} of a subtype is the same as the 18156@cite{Object_Size} of 18157the type from which it is obtained. 18158 18159@item 18160The @cite{Object_Size} of a derived base type is copied from the parent 18161base type, and the @cite{Object_Size} of a derived first subtype is copied 18162from the parent first subtype. 18163@end itemize 18164 18165The @cite{Value_Size} attribute 18166is the (minimum) number of bits required to store a value 18167of the type. 18168This value is used to determine how tightly to pack 18169records or arrays with components of this type, and also affects 18170the semantics of unchecked conversion (unchecked conversions where 18171the @cite{Value_Size} values differ generate a warning, and are potentially 18172target dependent). 18173 18174The default rules for the value of @cite{Value_Size} are as follows: 18175 18176 18177@itemize * 18178 18179@item 18180The @cite{Value_Size} for a base subtype is the minimum number of bits 18181required to store all values of the type (including the sign bit 18182only if negative values are possible). 18183 18184@item 18185If a subtype statically matches the first subtype of a given type, then it has 18186by default the same @cite{Value_Size} as the first subtype. This is a 18187consequence of RM 13.1(14): "if two subtypes statically match, 18188then their subtype-specific aspects are the same".) 18189 18190@item 18191All other subtypes have a @cite{Value_Size} corresponding to the minimum 18192number of bits required to store all values of the subtype. For 18193dynamic bounds, it is assumed that the value can range down or up 18194to the corresponding bound of the ancestor 18195@end itemize 18196 18197The RM defined attribute @cite{Size} corresponds to the 18198@cite{Value_Size} attribute. 18199 18200The @cite{Size} attribute may be defined for a first-named subtype. This sets 18201the @cite{Value_Size} of 18202the first-named subtype to the given value, and the 18203@cite{Object_Size} of this first-named subtype to the given value padded up 18204to an appropriate boundary. It is a consequence of the default rules 18205above that this @cite{Object_Size} will apply to all further subtypes. On the 18206other hand, @cite{Value_Size} is affected only for the first subtype, any 18207dynamic subtypes obtained from it directly, and any statically matching 18208subtypes. The @cite{Value_Size} of any other static subtypes is not affected. 18209 18210@cite{Value_Size} and 18211@cite{Object_Size} may be explicitly set for any subtype using 18212an attribute definition clause. Note that the use of these attributes 18213can cause the RM 13.1(14) rule to be violated. If two access types 18214reference aliased objects whose subtypes have differing @cite{Object_Size} 18215values as a result of explicit attribute definition clauses, then it 18216is illegal to convert from one access subtype to the other. For a more 18217complete description of this additional legality rule, see the 18218description of the @cite{Object_Size} attribute. 18219 18220To get a feel for the difference, consider the following examples (note 18221that in each case the base is @cite{Short_Short_Integer} with a size of 8): 18222 18223 18224@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 18225@headitem 18226 18227Type or subtype declaration 18228 18229@tab 18230 18231Object_Size 18232 18233@tab 18234 18235Value_Size 18236 18237@item 18238 18239@code{type x1 is range 0 .. 5;} 18240 18241@tab 18242 182438 18244 18245@tab 18246 182473 18248 18249@item 18250 18251@code{type x2 is range 0 .. 5;} 18252@code{for x2'size use 12;} 18253 18254@tab 18255 1825616 18257 18258@tab 18259 1826012 18261 18262@item 18263 18264@code{subtype x3 is x2 range 0 .. 3;} 18265 18266@tab 18267 1826816 18269 18270@tab 18271 182722 18273 18274@item 18275 18276@code{subtype x4 is x2'base range 0 .. 10;} 18277 18278@tab 18279 182808 18281 18282@tab 18283 182844 18285 18286@item 18287 18288@code{dynamic : x2'Base range -64 .. +63;} 18289 18290@tab 18291 18292@tab 18293 18294@item 18295 18296@code{subtype x5 is x2 range 0 .. dynamic;} 18297 18298@tab 18299 1830016 18301 18302@tab 18303 183043* 18305 18306@item 18307 18308@code{subtype x6 is x2'base range 0 .. dynamic;} 18309 18310@tab 18311 183128 18313 18314@tab 18315 183167* 18317 18318@end multitable 18319 18320 18321Note: the entries marked '*' are not actually specified by the Ada 18322Reference Manual, which has nothing to say about size in the dynamic 18323case. What GNAT does is to allocate sufficient bits to accomodate any 18324possible dynamic values for the bounds at run-time. 18325 18326So far, so good, but GNAT has to obey the RM rules, so the question is 18327under what conditions must the RM @cite{Size} be used. 18328The following is a list 18329of the occasions on which the RM @cite{Size} must be used: 18330 18331 18332@itemize * 18333 18334@item 18335Component size for packed arrays or records 18336 18337@item 18338Value of the attribute @cite{Size} for a type 18339 18340@item 18341Warning about sizes not matching for unchecked conversion 18342@end itemize 18343 18344For record types, the @cite{Object_Size} is always a multiple of the 18345alignment of the type (this is true for all types). In some cases the 18346@cite{Value_Size} can be smaller. Consider: 18347 18348@example 18349type R is record 18350 X : Integer; 18351 Y : Character; 18352end record; 18353@end example 18354 18355On a typical 32-bit architecture, the X component will be four bytes, and 18356require four-byte alignment, and the Y component will be one byte. In this 18357case @cite{R'Value_Size} will be 40 (bits) since this is the minimum size 18358required to store a value of this type, and for example, it is permissible 18359to have a component of type R in an outer array whose component size is 18360specified to be 48 bits. However, @cite{R'Object_Size} will be 64 (bits), 18361since it must be rounded up so that this value is a multiple of the 18362alignment (4 bytes = 32 bits). 18363 18364For all other types, the @cite{Object_Size} 18365and @cite{Value_Size} are the same (and equivalent to the RM attribute @cite{Size}). 18366Only @cite{Size} may be specified for such types. 18367 18368Note that @cite{Value_Size} can be used to force biased representation 18369for a particular subtype. Consider this example: 18370 18371@example 18372type R is (A, B, C, D, E, F); 18373subtype RAB is R range A .. B; 18374subtype REF is R range E .. F; 18375@end example 18376 18377By default, @cite{RAB} 18378has a size of 1 (sufficient to accommodate the representation 18379of @cite{A} and @cite{B}, 0 and 1), and @cite{REF} 18380has a size of 3 (sufficient to accommodate the representation 18381of @cite{E} and @cite{F}, 4 and 5). But if we add the 18382following @cite{Value_Size} attribute definition clause: 18383 18384@example 18385for REF'Value_Size use 1; 18386@end example 18387 18388then biased representation is forced for @cite{REF}, 18389and 0 will represent @cite{E} and 1 will represent @cite{F}. 18390A warning is issued when a @cite{Value_Size} attribute 18391definition clause forces biased representation. This 18392warning can be turned off using @cite{-gnatw.B}. 18393 18394@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 18395@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{237}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{238} 18396@section Component_Size Clauses 18397 18398 18399@geindex Component_Size Clause 18400 18401Normally, the value specified in a component size clause must be consistent 18402with the subtype of the array component with regard to size and alignment. 18403In other words, the value specified must be at least equal to the size 18404of this subtype, and must be a multiple of the alignment value. 18405 18406In addition, component size clauses are allowed which cause the array 18407to be packed, by specifying a smaller value. A first case is for 18408component size values in the range 1 through 63. The value specified 18409must not be smaller than the Size of the subtype. GNAT will accurately 18410honor all packing requests in this range. For example, if we have: 18411 18412@example 18413type r is array (1 .. 8) of Natural; 18414for r'Component_Size use 31; 18415@end example 18416 18417then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 18418Of course access to the components of such an array is considerably 18419less efficient than if the natural component size of 32 is used. 18420A second case is when the subtype of the component is a record type 18421padded because of its default alignment. For example, if we have: 18422 18423@example 18424type r is record 18425 i : Integer; 18426 j : Integer; 18427 b : Boolean; 18428end record; 18429 18430type a is array (1 .. 8) of r; 18431for a'Component_Size use 72; 18432@end example 18433 18434then the resulting array has a length of 72 bytes, instead of 96 bytes 18435if the alignment of the record (4) was obeyed. 18436 18437Note that there is no point in giving both a component size clause 18438and a pragma Pack for the same array type. if such duplicate 18439clauses are given, the pragma Pack will be ignored. 18440 18441@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 18442@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{239}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{23a} 18443@section Bit_Order Clauses 18444 18445 18446@geindex Bit_Order Clause 18447 18448@geindex bit ordering 18449 18450@geindex ordering 18451@geindex of bits 18452 18453For record subtypes, GNAT permits the specification of the @cite{Bit_Order} 18454attribute. The specification may either correspond to the default bit 18455order for the target, in which case the specification has no effect and 18456places no additional restrictions, or it may be for the non-standard 18457setting (that is the opposite of the default). 18458 18459In the case where the non-standard value is specified, the effect is 18460to renumber bits within each byte, but the ordering of bytes is not 18461affected. There are certain 18462restrictions placed on component clauses as follows: 18463 18464 18465@itemize * 18466 18467@item 18468Components fitting within a single storage unit. 18469 18470These are unrestricted, and the effect is merely to renumber bits. For 18471example if we are on a little-endian machine with @cite{Low_Order_First} 18472being the default, then the following two declarations have exactly 18473the same effect: 18474 18475@example 18476type R1 is record 18477 A : Boolean; 18478 B : Integer range 1 .. 120; 18479end record; 18480 18481for R1 use record 18482 A at 0 range 0 .. 0; 18483 B at 0 range 1 .. 7; 18484end record; 18485 18486type R2 is record 18487 A : Boolean; 18488 B : Integer range 1 .. 120; 18489end record; 18490 18491for R2'Bit_Order use High_Order_First; 18492 18493for R2 use record 18494 A at 0 range 7 .. 7; 18495 B at 0 range 0 .. 6; 18496end record; 18497@end example 18498 18499The useful application here is to write the second declaration with the 18500@cite{Bit_Order} attribute definition clause, and know that it will be treated 18501the same, regardless of whether the target is little-endian or big-endian. 18502 18503@item 18504Components occupying an integral number of bytes. 18505 18506These are components that exactly fit in two or more bytes. Such component 18507declarations are allowed, but have no effect, since it is important to realize 18508that the @cite{Bit_Order} specification does not affect the ordering of bytes. 18509In particular, the following attempt at getting an endian-independent integer 18510does not work: 18511 18512@example 18513type R2 is record 18514 A : Integer; 18515end record; 18516 18517for R2'Bit_Order use High_Order_First; 18518 18519for R2 use record 18520 A at 0 range 0 .. 31; 18521end record; 18522@end example 18523 18524This declaration will result in a little-endian integer on a 18525little-endian machine, and a big-endian integer on a big-endian machine. 18526If byte flipping is required for interoperability between big- and 18527little-endian machines, this must be explicitly programmed. This capability 18528is not provided by @cite{Bit_Order}. 18529 18530@item 18531Components that are positioned across byte boundaries 18532 18533but do not occupy an integral number of bytes. Given that bytes are not 18534reordered, such fields would occupy a non-contiguous sequence of bits 18535in memory, requiring non-trivial code to reassemble. They are for this 18536reason not permitted, and any component clause specifying such a layout 18537will be flagged as illegal by GNAT. 18538@end itemize 18539 18540Since the misconception that Bit_Order automatically deals with all 18541endian-related incompatibilities is a common one, the specification of 18542a component field that is an integral number of bytes will always 18543generate a warning. This warning may be suppressed using @cite{pragma Warnings (Off)} 18544if desired. The following section contains additional 18545details regarding the issue of byte ordering. 18546 18547@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 18548@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{23b}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{23c} 18549@section Effect of Bit_Order on Byte Ordering 18550 18551 18552@geindex byte ordering 18553 18554@geindex ordering 18555@geindex of bytes 18556 18557In this section we will review the effect of the @cite{Bit_Order} attribute 18558definition clause on byte ordering. Briefly, it has no effect at all, but 18559a detailed example will be helpful. Before giving this 18560example, let us review the precise 18561definition of the effect of defining @cite{Bit_Order}. The effect of a 18562non-standard bit order is described in section 13.5.3 of the Ada 18563Reference Manual: 18564 18565@quotation 18566 18567"2 A bit ordering is a method of interpreting the meaning of 18568the storage place attributes." 18569@end quotation 18570 18571To understand the precise definition of storage place attributes in 18572this context, we visit section 13.5.1 of the manual: 18573 18574@quotation 18575 18576"13 A record_representation_clause (without the mod_clause) 18577specifies the layout. The storage place attributes (see 13.5.2) 18578are taken from the values of the position, first_bit, and last_bit 18579expressions after normalizing those values so that first_bit is 18580less than Storage_Unit." 18581@end quotation 18582 18583The critical point here is that storage places are taken from 18584the values after normalization, not before. So the @cite{Bit_Order} 18585interpretation applies to normalized values. The interpretation 18586is described in the later part of the 13.5.3 paragraph: 18587 18588@quotation 18589 18590"2 A bit ordering is a method of interpreting the meaning of 18591the storage place attributes. High_Order_First (known in the 18592vernacular as 'big endian') means that the first bit of a 18593storage element (bit 0) is the most significant bit (interpreting 18594the sequence of bits that represent a component as an unsigned 18595integer value). Low_Order_First (known in the vernacular as 18596'little endian') means the opposite: the first bit is the 18597least significant." 18598@end quotation 18599 18600Note that the numbering is with respect to the bits of a storage 18601unit. In other words, the specification affects only the numbering 18602of bits within a single storage unit. 18603 18604We can make the effect clearer by giving an example. 18605 18606Suppose that we have an external device which presents two bytes, the first 18607byte presented, which is the first (low addressed byte) of the two byte 18608record is called Master, and the second byte is called Slave. 18609 18610The left most (most significant bit is called Control for each byte, and 18611the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost 18612(least significant) bit. 18613 18614On a big-endian machine, we can write the following representation clause 18615 18616@example 18617type Data is record 18618 Master_Control : Bit; 18619 Master_V1 : Bit; 18620 Master_V2 : Bit; 18621 Master_V3 : Bit; 18622 Master_V4 : Bit; 18623 Master_V5 : Bit; 18624 Master_V6 : Bit; 18625 Master_V7 : Bit; 18626 Slave_Control : Bit; 18627 Slave_V1 : Bit; 18628 Slave_V2 : Bit; 18629 Slave_V3 : Bit; 18630 Slave_V4 : Bit; 18631 Slave_V5 : Bit; 18632 Slave_V6 : Bit; 18633 Slave_V7 : Bit; 18634end record; 18635 18636for Data use record 18637 Master_Control at 0 range 0 .. 0; 18638 Master_V1 at 0 range 1 .. 1; 18639 Master_V2 at 0 range 2 .. 2; 18640 Master_V3 at 0 range 3 .. 3; 18641 Master_V4 at 0 range 4 .. 4; 18642 Master_V5 at 0 range 5 .. 5; 18643 Master_V6 at 0 range 6 .. 6; 18644 Master_V7 at 0 range 7 .. 7; 18645 Slave_Control at 1 range 0 .. 0; 18646 Slave_V1 at 1 range 1 .. 1; 18647 Slave_V2 at 1 range 2 .. 2; 18648 Slave_V3 at 1 range 3 .. 3; 18649 Slave_V4 at 1 range 4 .. 4; 18650 Slave_V5 at 1 range 5 .. 5; 18651 Slave_V6 at 1 range 6 .. 6; 18652 Slave_V7 at 1 range 7 .. 7; 18653end record; 18654@end example 18655 18656Now if we move this to a little endian machine, then the bit ordering within 18657the byte is backwards, so we have to rewrite the record rep clause as: 18658 18659@example 18660for Data use record 18661 Master_Control at 0 range 7 .. 7; 18662 Master_V1 at 0 range 6 .. 6; 18663 Master_V2 at 0 range 5 .. 5; 18664 Master_V3 at 0 range 4 .. 4; 18665 Master_V4 at 0 range 3 .. 3; 18666 Master_V5 at 0 range 2 .. 2; 18667 Master_V6 at 0 range 1 .. 1; 18668 Master_V7 at 0 range 0 .. 0; 18669 Slave_Control at 1 range 7 .. 7; 18670 Slave_V1 at 1 range 6 .. 6; 18671 Slave_V2 at 1 range 5 .. 5; 18672 Slave_V3 at 1 range 4 .. 4; 18673 Slave_V4 at 1 range 3 .. 3; 18674 Slave_V5 at 1 range 2 .. 2; 18675 Slave_V6 at 1 range 1 .. 1; 18676 Slave_V7 at 1 range 0 .. 0; 18677end record; 18678@end example 18679 18680It is a nuisance to have to rewrite the clause, especially if 18681the code has to be maintained on both machines. However, 18682this is a case that we can handle with the 18683@cite{Bit_Order} attribute if it is implemented. 18684Note that the implementation is not required on byte addressed 18685machines, but it is indeed implemented in GNAT. 18686This means that we can simply use the 18687first record clause, together with the declaration 18688 18689@example 18690for Data'Bit_Order use High_Order_First; 18691@end example 18692 18693and the effect is what is desired, namely the layout is exactly the same, 18694independent of whether the code is compiled on a big-endian or little-endian 18695machine. 18696 18697The important point to understand is that byte ordering is not affected. 18698A @cite{Bit_Order} attribute definition never affects which byte a field 18699ends up in, only where it ends up in that byte. 18700To make this clear, let us rewrite the record rep clause of the previous 18701example as: 18702 18703@example 18704for Data'Bit_Order use High_Order_First; 18705for Data use record 18706 Master_Control at 0 range 0 .. 0; 18707 Master_V1 at 0 range 1 .. 1; 18708 Master_V2 at 0 range 2 .. 2; 18709 Master_V3 at 0 range 3 .. 3; 18710 Master_V4 at 0 range 4 .. 4; 18711 Master_V5 at 0 range 5 .. 5; 18712 Master_V6 at 0 range 6 .. 6; 18713 Master_V7 at 0 range 7 .. 7; 18714 Slave_Control at 0 range 8 .. 8; 18715 Slave_V1 at 0 range 9 .. 9; 18716 Slave_V2 at 0 range 10 .. 10; 18717 Slave_V3 at 0 range 11 .. 11; 18718 Slave_V4 at 0 range 12 .. 12; 18719 Slave_V5 at 0 range 13 .. 13; 18720 Slave_V6 at 0 range 14 .. 14; 18721 Slave_V7 at 0 range 15 .. 15; 18722end record; 18723@end example 18724 18725This is exactly equivalent to saying (a repeat of the first example): 18726 18727@example 18728for Data'Bit_Order use High_Order_First; 18729for Data use record 18730 Master_Control at 0 range 0 .. 0; 18731 Master_V1 at 0 range 1 .. 1; 18732 Master_V2 at 0 range 2 .. 2; 18733 Master_V3 at 0 range 3 .. 3; 18734 Master_V4 at 0 range 4 .. 4; 18735 Master_V5 at 0 range 5 .. 5; 18736 Master_V6 at 0 range 6 .. 6; 18737 Master_V7 at 0 range 7 .. 7; 18738 Slave_Control at 1 range 0 .. 0; 18739 Slave_V1 at 1 range 1 .. 1; 18740 Slave_V2 at 1 range 2 .. 2; 18741 Slave_V3 at 1 range 3 .. 3; 18742 Slave_V4 at 1 range 4 .. 4; 18743 Slave_V5 at 1 range 5 .. 5; 18744 Slave_V6 at 1 range 6 .. 6; 18745 Slave_V7 at 1 range 7 .. 7; 18746end record; 18747@end example 18748 18749Why are they equivalent? Well take a specific field, the @cite{Slave_V2} 18750field. The storage place attributes are obtained by normalizing the 18751values given so that the @cite{First_Bit} value is less than 8. After 18752normalizing the values (0,10,10) we get (1,2,2) which is exactly what 18753we specified in the other case. 18754 18755Now one might expect that the @cite{Bit_Order} attribute might affect 18756bit numbering within the entire record component (two bytes in this 18757case, thus affecting which byte fields end up in), but that is not 18758the way this feature is defined, it only affects numbering of bits, 18759not which byte they end up in. 18760 18761Consequently it never makes sense to specify a starting bit number 18762greater than 7 (for a byte addressable field) if an attribute 18763definition for @cite{Bit_Order} has been given, and indeed it 18764may be actively confusing to specify such a value, so the compiler 18765generates a warning for such usage. 18766 18767If you do need to control byte ordering then appropriate conditional 18768values must be used. If in our example, the slave byte came first on 18769some machines we might write: 18770 18771@example 18772Master_Byte_First constant Boolean := ...; 18773 18774Master_Byte : constant Natural := 18775 1 - Boolean'Pos (Master_Byte_First); 18776Slave_Byte : constant Natural := 18777 Boolean'Pos (Master_Byte_First); 18778 18779for Data'Bit_Order use High_Order_First; 18780for Data use record 18781 Master_Control at Master_Byte range 0 .. 0; 18782 Master_V1 at Master_Byte range 1 .. 1; 18783 Master_V2 at Master_Byte range 2 .. 2; 18784 Master_V3 at Master_Byte range 3 .. 3; 18785 Master_V4 at Master_Byte range 4 .. 4; 18786 Master_V5 at Master_Byte range 5 .. 5; 18787 Master_V6 at Master_Byte range 6 .. 6; 18788 Master_V7 at Master_Byte range 7 .. 7; 18789 Slave_Control at Slave_Byte range 0 .. 0; 18790 Slave_V1 at Slave_Byte range 1 .. 1; 18791 Slave_V2 at Slave_Byte range 2 .. 2; 18792 Slave_V3 at Slave_Byte range 3 .. 3; 18793 Slave_V4 at Slave_Byte range 4 .. 4; 18794 Slave_V5 at Slave_Byte range 5 .. 5; 18795 Slave_V6 at Slave_Byte range 6 .. 6; 18796 Slave_V7 at Slave_Byte range 7 .. 7; 18797end record; 18798@end example 18799 18800Now to switch between machines, all that is necessary is 18801to set the boolean constant @cite{Master_Byte_First} in 18802an appropriate manner. 18803 18804@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 18805@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{23d}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{23e} 18806@section Pragma Pack for Arrays 18807 18808 18809@geindex Pragma Pack (for arrays) 18810 18811Pragma @cite{Pack} applied to an array has no effect unless the component type 18812is packable. For a component type to be packable, it must be one of the 18813following cases: 18814 18815 18816@itemize * 18817 18818@item 18819Any scalar type 18820 18821@item 18822Any type whose size is specified with a size clause 18823 18824@item 18825Any packed array type with a static size 18826 18827@item 18828Any record type padded because of its default alignment 18829@end itemize 18830 18831For all these cases, if the component subtype size is in the range 188321 through 63, then the effect of the pragma @cite{Pack} is exactly as though a 18833component size were specified giving the component subtype size. 18834For example if we have: 18835 18836@example 18837type r is range 0 .. 17; 18838 18839type ar is array (1 .. 8) of r; 18840pragma Pack (ar); 18841@end example 18842 18843Then the component size of @cite{ar} will be set to 5 (i.e., to @cite{r'size}, 18844and the size of the array @cite{ar} will be exactly 40 bits. 18845 18846Note that in some cases this rather fierce approach to packing can produce 18847unexpected effects. For example, in Ada 95 and Ada 2005, 18848subtype @cite{Natural} typically has a size of 31, meaning that if you 18849pack an array of @cite{Natural}, you get 31-bit 18850close packing, which saves a few bits, but results in far less efficient 18851access. Since many other Ada compilers will ignore such a packing request, 18852GNAT will generate a warning on some uses of pragma @cite{Pack} that it guesses 18853might not be what is intended. You can easily remove this warning by 18854using an explicit @cite{Component_Size} setting instead, which never generates 18855a warning, since the intention of the programmer is clear in this case. 18856 18857GNAT treats packed arrays in one of two ways. If the size of the array is 18858known at compile time and is less than 64 bits, then internally the array 18859is represented as a single modular type, of exactly the appropriate number 18860of bits. If the length is greater than 63 bits, or is not known at compile 18861time, then the packed array is represented as an array of bytes, and the 18862length is always a multiple of 8 bits. 18863 18864Note that to represent a packed array as a modular type, the alignment must 18865be suitable for the modular type involved. For example, on typical machines 18866a 32-bit packed array will be represented by a 32-bit modular integer with 18867an alignment of four bytes. If you explicitly override the default alignment 18868with an alignment clause that is too small, the modular representation 18869cannot be used. For example, consider the following set of declarations: 18870 18871@example 18872type R is range 1 .. 3; 18873type S is array (1 .. 31) of R; 18874for S'Component_Size use 2; 18875for S'Size use 62; 18876for S'Alignment use 1; 18877@end example 18878 18879If the alignment clause were not present, then a 62-bit modular 18880representation would be chosen (typically with an alignment of 4 or 8 18881bytes depending on the target). But the default alignment is overridden 18882with the explicit alignment clause. This means that the modular 18883representation cannot be used, and instead the array of bytes 18884representation must be used, meaning that the length must be a multiple 18885of 8. Thus the above set of declarations will result in a diagnostic 18886rejecting the size clause and noting that the minimum size allowed is 64. 18887 18888@geindex Pragma Pack (for type Natural) 18889 18890@geindex Pragma Pack warning 18891 18892One special case that is worth noting occurs when the base type of the 18893component size is 8/16/32 and the subtype is one bit less. Notably this 18894occurs with subtype @cite{Natural}. Consider: 18895 18896@example 18897type Arr is array (1 .. 32) of Natural; 18898pragma Pack (Arr); 18899@end example 18900 18901In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 18902since typically @cite{Natural'Size} is 32 in Ada 83, and in any case most 18903Ada 83 compilers did not attempt 31 bit packing. 18904 18905In Ada 95 and Ada 2005, @cite{Natural'Size} is required to be 31. Furthermore, 18906GNAT really does pack 31-bit subtype to 31 bits. This may result in a 18907substantial unintended performance penalty when porting legacy Ada 83 code. 18908To help prevent this, GNAT generates a warning in such cases. If you really 18909want 31 bit packing in a case like this, you can set the component size 18910explicitly: 18911 18912@example 18913type Arr is array (1 .. 32) of Natural; 18914for Arr'Component_Size use 31; 18915@end example 18916 18917Here 31-bit packing is achieved as required, and no warning is generated, 18918since in this case the programmer intention is clear. 18919 18920@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 18921@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{23f}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{240} 18922@section Pragma Pack for Records 18923 18924 18925@geindex Pragma Pack (for records) 18926 18927Pragma @cite{Pack} applied to a record will pack the components to reduce 18928wasted space from alignment gaps and by reducing the amount of space 18929taken by components. We distinguish between @emph{packable} components and 18930@emph{non-packable} components. 18931Components of the following types are considered packable: 18932 18933 18934@itemize * 18935 18936@item 18937Components of a primitive type are packable unless they are aliased 18938or of an atomic type. 18939 18940@item 18941Small packed arrays, whose size does not exceed 64 bits, and where the 18942size is statically known at compile time, are represented internally 18943as modular integers, and so they are also packable. 18944@end itemize 18945 18946All packable components occupy the exact number of bits corresponding to 18947their @cite{Size} value, and are packed with no padding bits, i.e., they 18948can start on an arbitrary bit boundary. 18949 18950All other types are non-packable, they occupy an integral number of 18951storage units, and 18952are placed at a boundary corresponding to their alignment requirements. 18953 18954For example, consider the record 18955 18956@example 18957type Rb1 is array (1 .. 13) of Boolean; 18958pragma Pack (Rb1); 18959 18960type Rb2 is array (1 .. 65) of Boolean; 18961pragma Pack (Rb2); 18962 18963type AF is new Float with Atomic; 18964 18965type X2 is record 18966 L1 : Boolean; 18967 L2 : Duration; 18968 L3 : AF; 18969 L4 : Boolean; 18970 L5 : Rb1; 18971 L6 : Rb2; 18972end record; 18973pragma Pack (X2); 18974@end example 18975 18976The representation for the record X2 is as follows: 18977 18978@example 18979for X2'Size use 224; 18980for X2 use record 18981 L1 at 0 range 0 .. 0; 18982 L2 at 0 range 1 .. 64; 18983 L3 at 12 range 0 .. 31; 18984 L4 at 16 range 0 .. 0; 18985 L5 at 16 range 1 .. 13; 18986 L6 at 18 range 0 .. 71; 18987end record; 18988@end example 18989 18990Studying this example, we see that the packable fields @cite{L1} 18991and @cite{L2} are 18992of length equal to their sizes, and placed at specific bit boundaries (and 18993not byte boundaries) to 18994eliminate padding. But @cite{L3} is of a non-packable float type (because 18995it is aliased), so it is on the next appropriate alignment boundary. 18996 18997The next two fields are fully packable, so @cite{L4} and @cite{L5} are 18998minimally packed with no gaps. However, type @cite{Rb2} is a packed 18999array that is longer than 64 bits, so it is itself non-packable. Thus 19000the @cite{L6} field is aligned to the next byte boundary, and takes an 19001integral number of bytes, i.e., 72 bits. 19002 19003@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19004@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{241}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{242} 19005@section Record Representation Clauses 19006 19007 19008@geindex Record Representation Clause 19009 19010Record representation clauses may be given for all record types, including 19011types obtained by record extension. Component clauses are allowed for any 19012static component. The restrictions on component clauses depend on the type 19013of the component. 19014 19015@geindex Component Clause 19016 19017For all components of an elementary type, the only restriction on component 19018clauses is that the size must be at least the 'Size value of the type 19019(actually the Value_Size). There are no restrictions due to alignment, 19020and such components may freely cross storage boundaries. 19021 19022Packed arrays with a size up to and including 64 bits are represented 19023internally using a modular type with the appropriate number of bits, and 19024thus the same lack of restriction applies. For example, if you declare: 19025 19026@example 19027type R is array (1 .. 49) of Boolean; 19028pragma Pack (R); 19029for R'Size use 49; 19030@end example 19031 19032then a component clause for a component of type R may start on any 19033specified bit boundary, and may specify a value of 49 bits or greater. 19034 19035For packed bit arrays that are longer than 64 bits, there are two 19036cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 19037including the important case of single bits or boolean values, then 19038there are no limitations on placement of such components, and they 19039may start and end at arbitrary bit boundaries. 19040 19041If the component size is not a power of 2 (e.g., 3 or 5), then 19042an array of this type longer than 64 bits must always be placed on 19043on a storage unit (byte) boundary and occupy an integral number 19044of storage units (bytes). Any component clause that does not 19045meet this requirement will be rejected. 19046 19047Any aliased component, or component of an aliased type, must 19048have its normal alignment and size. A component clause that 19049does not meet this requirement will be rejected. 19050 19051The tag field of a tagged type always occupies an address sized field at 19052the start of the record. No component clause may attempt to overlay this 19053tag. When a tagged type appears as a component, the tag field must have 19054proper alignment 19055 19056In the case of a record extension T1, of a type T, no component clause applied 19057to the type T1 can specify a storage location that would overlap the first 19058T'Size bytes of the record. 19059 19060For all other component types, including non-bit-packed arrays, 19061the component can be placed at an arbitrary bit boundary, 19062so for example, the following is permitted: 19063 19064@example 19065type R is array (1 .. 10) of Boolean; 19066for R'Size use 80; 19067 19068type Q is record 19069 G, H : Boolean; 19070 L, M : R; 19071end record; 19072 19073for Q use record 19074 G at 0 range 0 .. 0; 19075 H at 0 range 1 .. 1; 19076 L at 0 range 2 .. 81; 19077 R at 0 range 82 .. 161; 19078end record; 19079@end example 19080 19081Note: the above rules apply to recent releases of GNAT 5. 19082In GNAT 3, there are more severe restrictions on larger components. 19083For non-primitive types, including packed arrays with a size greater than 1908464 bits, component clauses must respect the alignment requirement of the 19085type, in particular, always starting on a byte boundary, and the length 19086must be a multiple of the storage unit. 19087 19088@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19089@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{243}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{244} 19090@section Handling of Records with Holes 19091 19092 19093@geindex Handling of Records with Holes 19094 19095As a result of alignment considerations, records may contain "holes" 19096or gaps 19097which do not correspond to the data bits of any of the components. 19098Record representation clauses can also result in holes in records. 19099 19100GNAT does not attempt to clear these holes, so in record objects, 19101they should be considered to hold undefined rubbish. The generated 19102equality routine just tests components so does not access these 19103undefined bits, and assignment and copy operations may or may not 19104preserve the contents of these holes (for assignments, the holes 19105in the target will in practice contain either the bits that are 19106present in the holes in the source, or the bits that were present 19107in the target before the assignment). 19108 19109If it is necessary to ensure that holes in records have all zero 19110bits, then record objects for which this initialization is desired 19111should be explicitly set to all zero values using Unchecked_Conversion 19112or address overlays. For example 19113 19114@example 19115type HRec is record 19116 C : Character; 19117 I : Integer; 19118end record; 19119@end example 19120 19121On typical machines, integers need to be aligned on a four-byte 19122boundary, resulting in three bytes of undefined rubbish following 19123the 8-bit field for C. To ensure that the hole in a variable of 19124type HRec is set to all zero bits, 19125you could for example do: 19126 19127@example 19128type Base is record 19129 Dummy1, Dummy2 : Integer := 0; 19130end record; 19131 19132BaseVar : Base; 19133RealVar : Hrec; 19134for RealVar'Address use BaseVar'Address; 19135@end example 19136 19137Now the 8-bytes of the value of RealVar start out containing all zero 19138bits. A safer approach is to just define dummy fields, avoiding the 19139holes, as in: 19140 19141@example 19142type HRec is record 19143 C : Character; 19144 Dummy1 : Short_Short_Integer := 0; 19145 Dummy2 : Short_Short_Integer := 0; 19146 Dummy3 : Short_Short_Integer := 0; 19147 I : Integer; 19148end record; 19149@end example 19150 19151And to make absolutely sure that the intent of this is followed, you 19152can use representation clauses: 19153 19154@example 19155for Hrec use record 19156 C at 0 range 0 .. 7; 19157 Dummy1 at 1 range 0 .. 7; 19158 Dummy2 at 2 range 0 .. 7; 19159 Dummy3 at 3 range 0 .. 7; 19160 I at 4 range 0 .. 31; 19161end record; 19162for Hrec'Size use 64; 19163@end example 19164 19165@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 19166@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{245}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{246} 19167@section Enumeration Clauses 19168 19169 19170The only restriction on enumeration clauses is that the range of values 19171must be representable. For the signed case, if one or more of the 19172representation values are negative, all values must be in the range: 19173 19174@example 19175System.Min_Int .. System.Max_Int 19176@end example 19177 19178For the unsigned case, where all values are nonnegative, the values must 19179be in the range: 19180 19181@example 191820 .. System.Max_Binary_Modulus; 19183@end example 19184 19185A @emph{confirming} representation clause is one in which the values range 19186from 0 in sequence, i.e., a clause that confirms the default representation 19187for an enumeration type. 19188Such a confirming representation 19189is permitted by these rules, and is specially recognized by the compiler so 19190that no extra overhead results from the use of such a clause. 19191 19192If an array has an index type which is an enumeration type to which an 19193enumeration clause has been applied, then the array is stored in a compact 19194manner. Consider the declarations: 19195 19196@example 19197type r is (A, B, C); 19198for r use (A => 1, B => 5, C => 10); 19199type t is array (r) of Character; 19200@end example 19201 19202The array type t corresponds to a vector with exactly three elements and 19203has a default size equal to @cite{3*Character'Size}. This ensures efficient 19204use of space, but means that accesses to elements of the array will incur 19205the overhead of converting representation values to the corresponding 19206positional values, (i.e., the value delivered by the @cite{Pos} attribute). 19207 19208@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 19209@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{247}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{248} 19210@section Address Clauses 19211 19212 19213@geindex Address Clause 19214 19215The reference manual allows a general restriction on representation clauses, 19216as found in RM 13.1(22): 19217 19218@quotation 19219 19220"An implementation need not support representation 19221items containing nonstatic expressions, except that 19222an implementation should support a representation item 19223for a given entity if each nonstatic expression in the 19224representation item is a name that statically denotes 19225a constant declared before the entity." 19226@end quotation 19227 19228In practice this is applicable only to address clauses, since this is the 19229only case in which a nonstatic expression is permitted by the syntax. As 19230the AARM notes in sections 13.1 (22.a-22.h): 19231 19232@quotation 19233 1923422.a Reason: This is to avoid the following sort of thing: 19235 1923622.b X : Integer := F(...); 19237Y : Address := G(...); 19238for X'Address use Y; 19239 1924022.c In the above, we have to evaluate the 19241initialization expression for X before we 19242know where to put the result. This seems 19243like an unreasonable implementation burden. 19244 1924522.d The above code should instead be written 19246like this: 19247 1924822.e Y : constant Address := G(...); 19249X : Integer := F(...); 19250for X'Address use Y; 19251 1925222.f This allows the expression 'Y' to be safely 19253evaluated before X is created. 19254 1925522.g The constant could be a formal parameter of mode in. 19256 1925722.h An implementation can support other nonstatic 19258expressions if it wants to. Expressions of type 19259Address are hardly ever static, but their value 19260might be known at compile time anyway in many 19261cases. 19262@end quotation 19263 19264GNAT does indeed permit many additional cases of nonstatic expressions. In 19265particular, if the type involved is elementary there are no restrictions 19266(since in this case, holding a temporary copy of the initialization value, 19267if one is present, is inexpensive). In addition, if there is no implicit or 19268explicit initialization, then there are no restrictions. GNAT will reject 19269only the case where all three of these conditions hold: 19270 19271 19272@itemize * 19273 19274@item 19275The type of the item is non-elementary (e.g., a record or array). 19276 19277@item 19278There is explicit or implicit initialization required for the object. 19279Note that access values are always implicitly initialized. 19280 19281@item 19282The address value is nonstatic. Here GNAT is more permissive than the 19283RM, and allows the address value to be the address of a previously declared 19284stand-alone variable, as long as it does not itself have an address clause. 19285 19286@example 19287Anchor : Some_Initialized_Type; 19288Overlay : Some_Initialized_Type; 19289for Overlay'Address use Anchor'Address; 19290@end example 19291 19292However, the prefix of the address clause cannot be an array component, or 19293a component of a discriminated record. 19294@end itemize 19295 19296As noted above in section 22.h, address values are typically nonstatic. In 19297particular the To_Address function, even if applied to a literal value, is 19298a nonstatic function call. To avoid this minor annoyance, GNAT provides 19299the implementation defined attribute 'To_Address. The following two 19300expressions have identical values: 19301 19302@geindex Attribute 19303 19304@geindex To_Address 19305 19306@example 19307To_Address (16#1234_0000#) 19308System'To_Address (16#1234_0000#); 19309@end example 19310 19311except that the second form is considered to be a static expression, and 19312thus when used as an address clause value is always permitted. 19313 19314Additionally, GNAT treats as static an address clause that is an 19315unchecked_conversion of a static integer value. This simplifies the porting 19316of legacy code, and provides a portable equivalent to the GNAT attribute 19317@cite{To_Address}. 19318 19319Another issue with address clauses is the interaction with alignment 19320requirements. When an address clause is given for an object, the address 19321value must be consistent with the alignment of the object (which is usually 19322the same as the alignment of the type of the object). If an address clause 19323is given that specifies an inappropriately aligned address value, then the 19324program execution is erroneous. 19325 19326Since this source of erroneous behavior can have unfortunate effects on 19327machines with strict alignment requirements, GNAT 19328checks (at compile time if possible, generating a warning, or at execution 19329time with a run-time check) that the alignment is appropriate. If the 19330run-time check fails, then @cite{Program_Error} is raised. This run-time 19331check is suppressed if range checks are suppressed, or if the special GNAT 19332check Alignment_Check is suppressed, or if 19333@cite{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 19334suppressed by default on non-strict alignment machines (such as the x86). 19335 19336Finally, GNAT does not permit overlaying of objects of controlled types or 19337composite types containing a controlled component. In most cases, the compiler 19338can detect an attempt at such overlays and will generate a warning at compile 19339time and a Program_Error exception at run time. 19340 19341@geindex Export 19342 19343An address clause cannot be given for an exported object. More 19344understandably the real restriction is that objects with an address 19345clause cannot be exported. This is because such variables are not 19346defined by the Ada program, so there is no external object to export. 19347 19348@geindex Import 19349 19350It is permissible to give an address clause and a pragma Import for the 19351same object. In this case, the variable is not really defined by the 19352Ada program, so there is no external symbol to be linked. The link name 19353and the external name are ignored in this case. The reason that we allow this 19354combination is that it provides a useful idiom to avoid unwanted 19355initializations on objects with address clauses. 19356 19357When an address clause is given for an object that has implicit or 19358explicit initialization, then by default initialization takes place. This 19359means that the effect of the object declaration is to overwrite the 19360memory at the specified address. This is almost always not what the 19361programmer wants, so GNAT will output a warning: 19362 19363@example 19364with System; 19365package G is 19366 type R is record 19367 M : Integer := 0; 19368 end record; 19369 19370 Ext : R; 19371 for Ext'Address use System'To_Address (16#1234_1234#); 19372 | 19373>>> warning: implicit initialization of "Ext" may 19374 modify overlaid storage 19375>>> warning: use pragma Import for "Ext" to suppress 19376 initialization (RM B(24)) 19377 19378end G; 19379@end example 19380 19381As indicated by the warning message, the solution is to use a (dummy) pragma 19382Import to suppress this initialization. The pragma tell the compiler that the 19383object is declared and initialized elsewhere. The following package compiles 19384without warnings (and the initialization is suppressed): 19385 19386@example 19387with System; 19388package G is 19389 type R is record 19390 M : Integer := 0; 19391 end record; 19392 19393 Ext : R; 19394 for Ext'Address use System'To_Address (16#1234_1234#); 19395 pragma Import (Ada, Ext); 19396end G; 19397@end example 19398 19399A final issue with address clauses involves their use for overlaying 19400variables, as in the following example: 19401 19402@geindex Overlaying of objects 19403 19404@example 19405A : Integer; 19406B : Integer; 19407for B'Address use A'Address; 19408@end example 19409 19410or alternatively, using the form recommended by the RM: 19411 19412@example 19413A : Integer; 19414Addr : constant Address := A'Address; 19415B : Integer; 19416for B'Address use Addr; 19417@end example 19418 19419In both of these cases, @cite{A} and @cite{B} become aliased to one another 19420via the address clause. This use of address clauses to overlay 19421variables, achieving an effect similar to unchecked conversion 19422was erroneous in Ada 83, but in Ada 95 and Ada 2005 19423the effect is implementation defined. Furthermore, the 19424Ada RM specifically recommends that in a situation 19425like this, @cite{B} should be subject to the following 19426implementation advice (RM 13.3(19)): 19427 19428@quotation 19429 19430"19 If the Address of an object is specified, or it is imported 19431or exported, then the implementation should not perform 19432optimizations based on assumptions of no aliases." 19433@end quotation 19434 19435GNAT follows this recommendation, and goes further by also applying 19436this recommendation to the overlaid variable (@cite{A} in the above example) 19437in this case. This means that the overlay works "as expected", in that 19438a modification to one of the variables will affect the value of the other. 19439 19440More generally, GNAT interprets this recommendation conservatively for 19441address clauses: in the cases other than overlays, it considers that the 19442object is effectively subject to pragma @cite{Volatile} and implements the 19443associated semantics. 19444 19445Note that when address clause overlays are used in this way, there is an 19446issue of unintentional initialization, as shown by this example: 19447 19448@example 19449package Overwrite_Record is 19450 type R is record 19451 A : Character := 'C'; 19452 B : Character := 'A'; 19453 end record; 19454 X : Short_Integer := 3; 19455 Y : R; 19456 for Y'Address use X'Address; 19457 | 19458>>> warning: default initialization of "Y" may 19459 modify "X", use pragma Import for "Y" to 19460 suppress initialization (RM B.1(24)) 19461 19462end Overwrite_Record; 19463@end example 19464 19465Here the default initialization of @cite{Y} will clobber the value 19466of @cite{X}, which justifies the warning. The warning notes that 19467this effect can be eliminated by adding a @cite{pragma Import} 19468which suppresses the initialization: 19469 19470@example 19471package Overwrite_Record is 19472 type R is record 19473 A : Character := 'C'; 19474 B : Character := 'A'; 19475 end record; 19476 X : Short_Integer := 3; 19477 Y : R; 19478 for Y'Address use X'Address; 19479 pragma Import (Ada, Y); 19480end Overwrite_Record; 19481@end example 19482 19483Note that the use of @cite{pragma Initialize_Scalars} may cause variables to 19484be initialized when they would not otherwise have been in the absence 19485of the use of this pragma. This may cause an overlay to have this 19486unintended clobbering effect. The compiler avoids this for scalar 19487types, but not for composite objects (where in general the effect 19488of @cite{Initialize_Scalars} is part of the initialization routine 19489for the composite object: 19490 19491@example 19492pragma Initialize_Scalars; 19493with Ada.Text_IO; use Ada.Text_IO; 19494procedure Overwrite_Array is 19495 type Arr is array (1 .. 5) of Integer; 19496 X : Arr := (others => 1); 19497 A : Arr; 19498 for A'Address use X'Address; 19499 | 19500>>> warning: default initialization of "A" may 19501 modify "X", use pragma Import for "A" to 19502 suppress initialization (RM B.1(24)) 19503 19504begin 19505 if X /= Arr'(others => 1) then 19506 Put_Line ("X was clobbered"); 19507 else 19508 Put_Line ("X was not clobbered"); 19509 end if; 19510end Overwrite_Array; 19511@end example 19512 19513The above program generates the warning as shown, and at execution 19514time, prints @cite{X was clobbered}. If the @cite{pragma Import} is 19515added as suggested: 19516 19517@example 19518pragma Initialize_Scalars; 19519with Ada.Text_IO; use Ada.Text_IO; 19520procedure Overwrite_Array is 19521 type Arr is array (1 .. 5) of Integer; 19522 X : Arr := (others => 1); 19523 A : Arr; 19524 for A'Address use X'Address; 19525 pragma Import (Ada, A); 19526begin 19527 if X /= Arr'(others => 1) then 19528 Put_Line ("X was clobbered"); 19529 else 19530 Put_Line ("X was not clobbered"); 19531 end if; 19532end Overwrite_Array; 19533@end example 19534 19535then the program compiles without the warning and when run will generate 19536the output @cite{X was not clobbered}. 19537 19538@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 19539@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{249}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{24a} 19540@section Use of Address Clauses for Memory-Mapped I/O 19541 19542 19543@geindex Memory-mapped I/O 19544 19545A common pattern is to use an address clause to map an atomic variable to 19546a location in memory that corresponds to a memory-mapped I/O operation or 19547operations, for example: 19548 19549@example 19550type Mem_Word is record 19551 A,B,C,D : Byte; 19552end record; 19553pragma Atomic (Mem_Word); 19554for Mem_Word_Size use 32; 19555 19556Mem : Mem_Word; 19557for Mem'Address use some-address; 19558... 19559Temp := Mem; 19560Temp.A := 32; 19561Mem := Temp; 19562@end example 19563 19564For a full access (reference or modification) of the variable (Mem) in this 19565case, as in the above examples, GNAT guarantees that the entire atomic word 19566will be accessed, in accordance with the RM C.6(15) clause. 19567 19568A problem arises with a component access such as: 19569 19570@example 19571Mem.A := 32; 19572@end example 19573 19574Note that the component A is not declared as atomic. This means that it is 19575not clear what this assignment means. It could correspond to full word read 19576and write as given in the first example, or on architectures that supported 19577such an operation it might be a single byte store instruction. The RM does 19578not have anything to say in this situation, and GNAT does not make any 19579guarantee. The code generated may vary from target to target. GNAT will issue 19580a warning in such a case: 19581 19582@example 19583Mem.A := 32; 19584| 19585>>> warning: access to non-atomic component of atomic array, 19586 may cause unexpected accesses to atomic object 19587@end example 19588 19589It is best to be explicit in this situation, by either declaring the 19590components to be atomic if you want the byte store, or explicitly writing 19591the full word access sequence if that is what the hardware requires. 19592Alternatively, if the full word access sequence is required, GNAT also 19593provides the pragma @cite{Volatile_Full_Access} which can be used in lieu of 19594pragma @cite{Atomic} and will give the additional guarantee. 19595 19596@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 19597@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{24b}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{24c} 19598@section Effect of Convention on Representation 19599 19600 19601@geindex Convention 19602@geindex effect on representation 19603 19604Normally the specification of a foreign language convention for a type or 19605an object has no effect on the chosen representation. In particular, the 19606representation chosen for data in GNAT generally meets the standard system 19607conventions, and for example records are laid out in a manner that is 19608consistent with C. This means that specifying convention C (for example) 19609has no effect. 19610 19611There are four exceptions to this general rule: 19612 19613 19614@itemize * 19615 19616@item 19617@emph{Convention Fortran and array subtypes}. 19618 19619If pragma Convention Fortran is specified for an array subtype, then in 19620accordance with the implementation advice in section 3.6.2(11) of the 19621Ada Reference Manual, the array will be stored in a Fortran-compatible 19622column-major manner, instead of the normal default row-major order. 19623 19624@item 19625@emph{Convention C and enumeration types} 19626 19627GNAT normally stores enumeration types in 8, 16, or 32 bits as required 19628to accommodate all values of the type. For example, for the enumeration 19629type declared by: 19630 19631@example 19632type Color is (Red, Green, Blue); 19633@end example 19634 196358 bits is sufficient to store all values of the type, so by default, objects 19636of type @cite{Color} will be represented using 8 bits. However, normal C 19637convention is to use 32 bits for all enum values in C, since enum values 19638are essentially of type int. If pragma @cite{Convention C} is specified for an 19639Ada enumeration type, then the size is modified as necessary (usually to 1964032 bits) to be consistent with the C convention for enum values. 19641 19642Note that this treatment applies only to types. If Convention C is given for 19643an enumeration object, where the enumeration type is not Convention C, then 19644Object_Size bits are allocated. For example, for a normal enumeration type, 19645with less than 256 elements, only 8 bits will be allocated for the object. 19646Since this may be a surprise in terms of what C expects, GNAT will issue a 19647warning in this situation. The warning can be suppressed by giving an explicit 19648size clause specifying the desired size. 19649 19650@item 19651@emph{Convention C/Fortran and Boolean types} 19652 19653In C, the usual convention for boolean values, that is values used for 19654conditions, is that zero represents false, and nonzero values represent 19655true. In Ada, the normal convention is that two specific values, typically 196560/1, are used to represent false/true respectively. 19657 19658Fortran has a similar convention for @cite{LOGICAL} values (any nonzero 19659value represents true). 19660 19661To accommodate the Fortran and C conventions, if a pragma Convention specifies 19662C or Fortran convention for a derived Boolean, as in the following example: 19663 19664@example 19665type C_Switch is new Boolean; 19666pragma Convention (C, C_Switch); 19667@end example 19668 19669then the GNAT generated code will treat any nonzero value as true. For truth 19670values generated by GNAT, the conventional value 1 will be used for True, but 19671when one of these values is read, any nonzero value is treated as True. 19672@end itemize 19673 19674@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 19675@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{24d}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{24e} 19676@section Conventions and Anonymous Access Types 19677 19678 19679@geindex Anonymous access types 19680 19681@geindex Convention for anonymous access types 19682 19683The RM is not entirely clear on convention handling in a number of cases, 19684and in particular, it is not clear on the convention to be given to 19685anonymous access types in general, and in particular what is to be 19686done for the case of anonymous access-to-subprogram. 19687 19688In GNAT, we decide that if an explicit Convention is applied 19689to an object or component, and its type is such an anonymous type, 19690then the convention will apply to this anonymous type as well. This 19691seems to make sense since it is anomolous in any case to have a 19692different convention for an object and its type, and there is clearly 19693no way to explicitly specify a convention for an anonymous type, since 19694it doesn't have a name to specify! 19695 19696Furthermore, we decide that if a convention is applied to a record type, 19697then this convention is inherited by any of its components that are of an 19698anonymous access type which do not have an explicitly specified convention. 19699 19700The following program shows these conventions in action: 19701 19702@example 19703package ConvComp is 19704 type Foo is range 1 .. 10; 19705 type T1 is record 19706 A : access function (X : Foo) return Integer; 19707 B : Integer; 19708 end record; 19709 pragma Convention (C, T1); 19710 19711 type T2 is record 19712 A : access function (X : Foo) return Integer; 19713 pragma Convention (C, A); 19714 B : Integer; 19715 end record; 19716 pragma Convention (COBOL, T2); 19717 19718 type T3 is record 19719 A : access function (X : Foo) return Integer; 19720 pragma Convention (COBOL, A); 19721 B : Integer; 19722 end record; 19723 pragma Convention (C, T3); 19724 19725 type T4 is record 19726 A : access function (X : Foo) return Integer; 19727 B : Integer; 19728 end record; 19729 pragma Convention (COBOL, T4); 19730 19731 function F (X : Foo) return Integer; 19732 pragma Convention (C, F); 19733 19734 function F (X : Foo) return Integer is (13); 19735 19736 TV1 : T1 := (F'Access, 12); -- OK 19737 TV2 : T2 := (F'Access, 13); -- OK 19738 19739 TV3 : T3 := (F'Access, 13); -- ERROR 19740 | 19741>>> subprogram "F" has wrong convention 19742>>> does not match access to subprogram declared at line 17 19743 38. TV4 : T4 := (F'Access, 13); -- ERROR 19744 | 19745>>> subprogram "F" has wrong convention 19746>>> does not match access to subprogram declared at line 24 19747 39. end ConvComp; 19748@end example 19749 19750@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 19751@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{24f}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{250} 19752@section Determining the Representations chosen by GNAT 19753 19754 19755@geindex Representation 19756@geindex determination of 19757 19758@geindex -gnatR (gcc) 19759 19760Although the descriptions in this section are intended to be complete, it is 19761often easier to simply experiment to see what GNAT accepts and what the 19762effect is on the layout of types and objects. 19763 19764As required by the Ada RM, if a representation clause is not accepted, then 19765it must be rejected as illegal by the compiler. However, when a 19766representation clause or pragma is accepted, there can still be questions 19767of what the compiler actually does. For example, if a partial record 19768representation clause specifies the location of some components and not 19769others, then where are the non-specified components placed? Or if pragma 19770@cite{Pack} is used on a record, then exactly where are the resulting 19771fields placed? The section on pragma @cite{Pack} in this chapter can be 19772used to answer the second question, but it is often easier to just see 19773what the compiler does. 19774 19775For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 19776with this option, then the compiler will output information on the actual 19777representations chosen, in a format similar to source representation 19778clauses. For example, if we compile the package: 19779 19780@example 19781package q is 19782 type r (x : boolean) is tagged record 19783 case x is 19784 when True => S : String (1 .. 100); 19785 when False => null; 19786 end case; 19787 end record; 19788 19789 type r2 is new r (false) with record 19790 y2 : integer; 19791 end record; 19792 19793 for r2 use record 19794 y2 at 16 range 0 .. 31; 19795 end record; 19796 19797 type x is record 19798 y : character; 19799 end record; 19800 19801 type x1 is array (1 .. 10) of x; 19802 for x1'component_size use 11; 19803 19804 type ia is access integer; 19805 19806 type Rb1 is array (1 .. 13) of Boolean; 19807 pragma Pack (rb1); 19808 19809 type Rb2 is array (1 .. 65) of Boolean; 19810 pragma Pack (rb2); 19811 19812 type x2 is record 19813 l1 : Boolean; 19814 l2 : Duration; 19815 l3 : Float; 19816 l4 : Boolean; 19817 l5 : Rb1; 19818 l6 : Rb2; 19819 end record; 19820 pragma Pack (x2); 19821end q; 19822@end example 19823 19824using the switch @emph{-gnatR} we obtain the following output: 19825 19826@example 19827Representation information for unit q 19828------------------------------------- 19829 19830for r'Size use ??; 19831for r'Alignment use 4; 19832for r use record 19833 x at 4 range 0 .. 7; 19834 _tag at 0 range 0 .. 31; 19835 s at 5 range 0 .. 799; 19836end record; 19837 19838for r2'Size use 160; 19839for r2'Alignment use 4; 19840for r2 use record 19841 x at 4 range 0 .. 7; 19842 _tag at 0 range 0 .. 31; 19843 _parent at 0 range 0 .. 63; 19844 y2 at 16 range 0 .. 31; 19845end record; 19846 19847for x'Size use 8; 19848for x'Alignment use 1; 19849for x use record 19850 y at 0 range 0 .. 7; 19851end record; 19852 19853for x1'Size use 112; 19854for x1'Alignment use 1; 19855for x1'Component_Size use 11; 19856 19857for rb1'Size use 13; 19858for rb1'Alignment use 2; 19859for rb1'Component_Size use 1; 19860 19861for rb2'Size use 72; 19862for rb2'Alignment use 1; 19863for rb2'Component_Size use 1; 19864 19865for x2'Size use 224; 19866for x2'Alignment use 4; 19867for x2 use record 19868 l1 at 0 range 0 .. 0; 19869 l2 at 0 range 1 .. 64; 19870 l3 at 12 range 0 .. 31; 19871 l4 at 16 range 0 .. 0; 19872 l5 at 16 range 1 .. 13; 19873 l6 at 18 range 0 .. 71; 19874end record; 19875@end example 19876 19877The Size values are actually the Object_Size, i.e., the default size that 19878will be allocated for objects of the type. 19879The @code{??} size for type r indicates that we have a variant record, and the 19880actual size of objects will depend on the discriminant value. 19881 19882The Alignment values show the actual alignment chosen by the compiler 19883for each record or array type. 19884 19885The record representation clause for type r shows where all fields 19886are placed, including the compiler generated tag field (whose location 19887cannot be controlled by the programmer). 19888 19889The record representation clause for the type extension r2 shows all the 19890fields present, including the parent field, which is a copy of the fields 19891of the parent type of r2, i.e., r1. 19892 19893The component size and size clauses for types rb1 and rb2 show 19894the exact effect of pragma @cite{Pack} on these arrays, and the record 19895representation clause for type x2 shows how pragma @cite{Pack} affects 19896this record type. 19897 19898In some cases, it may be useful to cut and paste the representation clauses 19899generated by the compiler into the original source to fix and guarantee 19900the actual representation to be used. 19901 19902@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 19903@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{251}@anchor{gnat_rm/standard_library_routines id1}@anchor{252} 19904@chapter Standard Library Routines 19905 19906 19907The Ada Reference Manual contains in Annex A a full description of an 19908extensive set of standard library routines that can be used in any Ada 19909program, and which must be provided by all Ada compilers. They are 19910analogous to the standard C library used by C programs. 19911 19912GNAT implements all of the facilities described in annex A, and for most 19913purposes the description in the Ada Reference Manual, or appropriate Ada 19914text book, will be sufficient for making use of these facilities. 19915 19916In the case of the input-output facilities, 19917@ref{f,,The Implementation of Standard I/O}, 19918gives details on exactly how GNAT interfaces to the 19919file system. For the remaining packages, the Ada Reference Manual 19920should be sufficient. The following is a list of the packages included, 19921together with a brief description of the functionality that is provided. 19922 19923For completeness, references are included to other predefined library 19924routines defined in other sections of the Ada Reference Manual (these are 19925cross-indexed from Annex A). For further details see the relevant 19926package declarations in the run-time library. In particular, a few units 19927are not implemented, as marked by the presence of pragma Unimplemented_Unit, 19928and in this case the package declaration contains comments explaining why 19929the unit is not implemented. 19930 19931 19932@table @asis 19933 19934@item @code{Ada} @emph{(A.2)} 19935 19936This is a parent package for all the standard library packages. It is 19937usually included implicitly in your program, and itself contains no 19938useful data or routines. 19939 19940@item @code{Ada.Assertions} @emph{(11.4.2)} 19941 19942@cite{Assertions} provides the @cite{Assert} subprograms, and also 19943the declaration of the @cite{Assertion_Error} exception. 19944 19945@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 19946 19947@cite{Asynchronous_Task_Control} provides low level facilities for task 19948synchronization. It is typically not implemented. See package spec for details. 19949 19950@item @code{Ada.Calendar} @emph{(9.6)} 19951 19952@cite{Calendar} provides time of day access, and routines for 19953manipulating times and durations. 19954 19955@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 19956 19957This package provides additional arithmetic 19958operations for @cite{Calendar}. 19959 19960@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 19961 19962This package provides formatting operations for @cite{Calendar}. 19963 19964@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 19965 19966This package provides additional @cite{Calendar} facilities 19967for handling time zones. 19968 19969@item @code{Ada.Characters} @emph{(A.3.1)} 19970 19971This is a dummy parent package that contains no useful entities 19972 19973@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 19974 19975This package provides character conversion functions. 19976 19977@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 19978 19979This package provides some basic character handling capabilities, 19980including classification functions for classes of characters (e.g., test 19981for letters, or digits). 19982 19983@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 19984 19985This package includes a complete set of definitions of the characters 19986that appear in type CHARACTER. It is useful for writing programs that 19987will run in international environments. For example, if you want an 19988upper case E with an acute accent in a string, it is often better to use 19989the definition of @cite{UC_E_Acute} in this package. Then your program 19990will print in an understandable manner even if your environment does not 19991support these extended characters. 19992 19993@item @code{Ada.Command_Line} @emph{(A.15)} 19994 19995This package provides access to the command line parameters and the name 19996of the current program (analogous to the use of @cite{argc} and @cite{argv} 19997in C), and also allows the exit status for the program to be set in a 19998system-independent manner. 19999 20000@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20001 20002This package provides text input and output of complex numbers. 20003 20004@item @code{Ada.Containers} @emph{(A.18.1)} 20005 20006A top level package providing a few basic definitions used by all the 20007following specific child packages that provide specific kinds of 20008containers. 20009@end table 20010 20011@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20012 20013@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20014 20015@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20016 20017@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20018 20019@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20020 20021@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20022 20023@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20024 20025@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20026 20027@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20028 20029@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20030 20031@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20032 20033@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20034 20035@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20036 20037@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20038 20039@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20040 20041@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20042 20043@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20044 20045@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20046 20047@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20048 20049@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20050 20051@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20052 20053@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20054 20055@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20056 20057 20058@table @asis 20059 20060@item @code{Ada.Directories} @emph{(A.16)} 20061 20062This package provides operations on directories. 20063 20064@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20065 20066This package provides additional directory operations handling 20067hiearchical file names. 20068 20069@item @code{Ada.Directories.Information} @emph{(A.16)} 20070 20071This is an implementation defined package for additional directory 20072operations, which is not implemented in GNAT. 20073 20074@item @code{Ada.Decimal} @emph{(F.2)} 20075 20076This package provides constants describing the range of decimal numbers 20077implemented, and also a decimal divide routine (analogous to the COBOL 20078verb DIVIDE ... GIVING ... REMAINDER ...) 20079 20080@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20081 20082This package provides input-output using a model of a set of records of 20083fixed-length, containing an arbitrary definite Ada type, indexed by an 20084integer record number. 20085 20086@item @code{Ada.Dispatching} @emph{(D.2.1)} 20087 20088A parent package containing definitions for task dispatching operations. 20089 20090@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20091 20092Not implemented in GNAT. 20093 20094@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20095 20096Not implemented in GNAT. 20097 20098@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20099 20100Not implemented in GNAT. 20101 20102@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20103 20104This package allows the priorities of a task to be adjusted dynamically 20105as the task is running. 20106 20107@item @code{Ada.Environment_Variables} @emph{(A.17)} 20108 20109This package provides facilities for accessing environment variables. 20110 20111@item @code{Ada.Exceptions} @emph{(11.4.1)} 20112 20113This package provides additional information on exceptions, and also 20114contains facilities for treating exceptions as data objects, and raising 20115exceptions with associated messages. 20116 20117@item @code{Ada.Execution_Time} @emph{(D.14)} 20118 20119Not implemented in GNAT. 20120 20121@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20122 20123Not implemented in GNAT. 20124 20125@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'} 20126 20127Not implemented in GNAT. 20128 20129@item @code{Ada.Finalization} @emph{(7.6)} 20130 20131This package contains the declarations and subprograms to support the 20132use of controlled types, providing for automatic initialization and 20133finalization (analogous to the constructors and destructors of C++). 20134 20135@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20136 20137A library level instantiation of Text_IO.Float_IO for type Float. 20138 20139@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 20140 20141A library level instantiation of Wide_Text_IO.Float_IO for type Float. 20142 20143@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 20144 20145A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 20146 20147@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 20148 20149A library level instantiation of Text_IO.Integer_IO for type Integer. 20150 20151@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 20152 20153A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 20154 20155@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 20156 20157A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 20158 20159@item @code{Ada.Interrupts} @emph{(C.3.2)} 20160 20161This package provides facilities for interfacing to interrupts, which 20162includes the set of signals or conditions that can be raised and 20163recognized as interrupts. 20164 20165@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 20166 20167This package provides the set of interrupt names (actually signal 20168or condition names) that can be handled by GNAT. 20169 20170@item @code{Ada.IO_Exceptions} @emph{(A.13)} 20171 20172This package defines the set of exceptions that can be raised by use of 20173the standard IO packages. 20174 20175@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 20176 20177This package provides a generic interface to generalized iterators. 20178 20179@item @code{Ada.Locales} @emph{(A.19)} 20180 20181This package provides declarations providing information (Language 20182and Country) about the current locale. 20183 20184@item @code{Ada.Numerics} 20185 20186This package contains some standard constants and exceptions used 20187throughout the numerics packages. Note that the constants pi and e are 20188defined here, and it is better to use these definitions than rolling 20189your own. 20190 20191@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 20192 20193Provides operations on arrays of complex numbers. 20194 20195@item @code{Ada.Numerics.Complex_Elementary_Functions} 20196 20197Provides the implementation of standard elementary functions (such as 20198log and trigonometric functions) operating on complex numbers using the 20199standard @cite{Float} and the @cite{Complex} and @cite{Imaginary} types 20200created by the package @cite{Numerics.Complex_Types}. 20201 20202@item @code{Ada.Numerics.Complex_Types} 20203 20204This is a predefined instantiation of 20205@cite{Numerics.Generic_Complex_Types} using @cite{Standard.Float} to 20206build the type @cite{Complex} and @cite{Imaginary}. 20207 20208@item @code{Ada.Numerics.Discrete_Random} 20209 20210This generic package provides a random number generator suitable for generating 20211uniformly distributed values of a specified discrete subtype. 20212 20213@item @code{Ada.Numerics.Float_Random} 20214 20215This package provides a random number generator suitable for generating 20216uniformly distributed floating point values in the unit interval. 20217 20218@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 20219 20220This is a generic version of the package that provides the 20221implementation of standard elementary functions (such as log and 20222trigonometric functions) for an arbitrary complex type. 20223 20224The following predefined instantiations of this package are provided: 20225 20226 20227@itemize * 20228 20229@item 20230@code{Short_Float} 20231 20232@cite{Ada.Numerics.Short_Complex_Elementary_Functions} 20233 20234@item 20235@code{Float} 20236 20237@cite{Ada.Numerics.Complex_Elementary_Functions} 20238 20239@item 20240@code{Long_Float} 20241 20242@cite{Ada.Numerics.Long_Complex_Elementary_Functions} 20243@end itemize 20244 20245@item @code{Ada.Numerics.Generic_Complex_Types} 20246 20247This is a generic package that allows the creation of complex types, 20248with associated complex arithmetic operations. 20249 20250The following predefined instantiations of this package exist 20251 20252 20253@itemize * 20254 20255@item 20256@code{Short_Float} 20257 20258@cite{Ada.Numerics.Short_Complex_Complex_Types} 20259 20260@item 20261@code{Float} 20262 20263@cite{Ada.Numerics.Complex_Complex_Types} 20264 20265@item 20266@code{Long_Float} 20267 20268@cite{Ada.Numerics.Long_Complex_Complex_Types} 20269@end itemize 20270 20271@item @code{Ada.Numerics.Generic_Elementary_Functions} 20272 20273This is a generic package that provides the implementation of standard 20274elementary functions (such as log an trigonometric functions) for an 20275arbitrary float type. 20276 20277The following predefined instantiations of this package exist 20278 20279 20280@itemize * 20281 20282@item 20283@code{Short_Float} 20284 20285@cite{Ada.Numerics.Short_Elementary_Functions} 20286 20287@item 20288@code{Float} 20289 20290@cite{Ada.Numerics.Elementary_Functions} 20291 20292@item 20293@code{Long_Float} 20294 20295@cite{Ada.Numerics.Long_Elementary_Functions} 20296@end itemize 20297 20298@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 20299 20300Generic operations on arrays of reals 20301 20302@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 20303 20304Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 20305 20306@item @code{Ada.Real_Time} @emph{(D.8)} 20307 20308This package provides facilities similar to those of @cite{Calendar}, but 20309operating with a finer clock suitable for real time control. Note that 20310annex D requires that there be no backward clock jumps, and GNAT generally 20311guarantees this behavior, but of course if the external clock on which 20312the GNAT runtime depends is deliberately reset by some external event, 20313then such a backward jump may occur. 20314 20315@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 20316 20317Not implemented in GNAT. 20318 20319@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 20320 20321This package provides input-output facilities for sequential files, 20322which can contain a sequence of values of a single type, which can be 20323any Ada type, including indefinite (unconstrained) types. 20324 20325@item @code{Ada.Storage_IO} @emph{(A.9)} 20326 20327This package provides a facility for mapping arbitrary Ada types to and 20328from a storage buffer. It is primarily intended for the creation of new 20329IO packages. 20330 20331@item @code{Ada.Streams} @emph{(13.13.1)} 20332 20333This is a generic package that provides the basic support for the 20334concept of streams as used by the stream attributes (@cite{Input}, 20335@cite{Output}, @cite{Read} and @cite{Write}). 20336 20337@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 20338 20339This package is a specialization of the type @cite{Streams} defined in 20340package @cite{Streams} together with a set of operations providing 20341Stream_IO capability. The Stream_IO model permits both random and 20342sequential access to a file which can contain an arbitrary set of values 20343of one or more Ada types. 20344 20345@item @code{Ada.Strings} @emph{(A.4.1)} 20346 20347This package provides some basic constants used by the string handling 20348packages. 20349 20350@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 20351 20352This package provides facilities for handling variable length 20353strings. The bounded model requires a maximum length. It is thus 20354somewhat more limited than the unbounded model, but avoids the use of 20355dynamic allocation or finalization. 20356 20357@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20358 20359Provides case-insensitive comparisons of bounded strings 20360 20361@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 20362 20363This package provides a generic hash function for bounded strings 20364 20365@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20366 20367This package provides a generic hash function for bounded strings that 20368converts the string to be hashed to lower case. 20369 20370@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 20371 20372This package provides a comparison function for bounded strings that works 20373in a case insensitive manner by converting to lower case before the comparison. 20374 20375@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 20376 20377This package provides facilities for handling fixed length strings. 20378 20379@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 20380 20381This package provides an equality function for fixed strings that compares 20382the strings after converting both to lower case. 20383 20384@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 20385 20386This package provides a case insensitive hash function for fixed strings that 20387converts the string to lower case before computing the hash. 20388 20389@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 20390 20391This package provides a comparison function for fixed strings that works 20392in a case insensitive manner by converting to lower case before the comparison. 20393 20394@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 20395 20396This package provides a hash function for strings. 20397 20398@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 20399 20400This package provides a hash function for strings that is case insensitive. 20401The string is converted to lower case before computing the hash. 20402 20403@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 20404 20405This package provides a comparison function for\strings that works 20406in a case insensitive manner by converting to lower case before the comparison. 20407 20408@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 20409 20410This package provides facilities for handling character mappings and 20411arbitrarily defined subsets of characters. For instance it is useful in 20412defining specialized translation tables. 20413 20414@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 20415 20416This package provides a standard set of predefined mappings and 20417predefined character sets. For example, the standard upper to lower case 20418conversion table is found in this package. Note that upper to lower case 20419conversion is non-trivial if you want to take the entire set of 20420characters, including extended characters like E with an acute accent, 20421into account. You should use the mappings in this package (rather than 20422adding 32 yourself) to do case mappings. 20423 20424@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 20425 20426This package provides facilities for handling variable length 20427strings. The unbounded model allows arbitrary length strings, but 20428requires the use of dynamic allocation and finalization. 20429 20430@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20431 20432Provides case-insensitive comparisons of unbounded strings 20433 20434@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 20435 20436This package provides a generic hash function for unbounded strings 20437 20438@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20439 20440This package provides a generic hash function for unbounded strings that 20441converts the string to be hashed to lower case. 20442 20443@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 20444 20445This package provides a comparison function for unbounded strings that works 20446in a case insensitive manner by converting to lower case before the comparison. 20447 20448@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 20449 20450This package provides basic definitions for dealing with UTF-encoded strings. 20451 20452@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 20453 20454This package provides conversion functions for UTF-encoded strings. 20455@end table 20456 20457@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 20458 20459@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 20460 20461 20462@table @asis 20463 20464@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 20465 20466These packages provide facilities for handling UTF encodings for 20467Strings, Wide_Strings and Wide_Wide_Strings. 20468@end table 20469 20470@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 20471 20472@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 20473 20474@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 20475 20476 20477@table @asis 20478 20479@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 20480 20481These packages provide analogous capabilities to the corresponding 20482packages without @code{Wide_} in the name, but operate with the types 20483@cite{Wide_String} and @cite{Wide_Character} instead of @cite{String} 20484and @cite{Character}. Versions of all the child packages are available. 20485@end table 20486 20487@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 20488 20489@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 20490 20491@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 20492 20493 20494@table @asis 20495 20496@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 20497 20498These packages provide analogous capabilities to the corresponding 20499packages without @code{Wide_} in the name, but operate with the types 20500@cite{Wide_Wide_String} and @cite{Wide_Wide_Character} instead 20501of @cite{String} and @cite{Character}. 20502 20503@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 20504 20505This package provides facilities for synchronizing tasks at a low level 20506with barriers. 20507 20508@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 20509 20510This package provides some standard facilities for controlling task 20511communication in a synchronous manner. 20512 20513@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 20514 20515Not implemented in GNAT. 20516 20517@item @code{Ada.Tags} 20518 20519This package contains definitions for manipulation of the tags of tagged 20520values. 20521 20522@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 20523 20524This package provides a way of constructing tagged class-wide values given 20525only the tag value. 20526 20527@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 20528 20529This package provides the capability of associating arbitrary 20530task-specific data with separate tasks. 20531 20532@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 20533 20534This package provides capabilities for task identification. 20535 20536@item @code{Ada.Task_Termination} @emph{(C.7.3)} 20537 20538This package provides control over task termination. 20539 20540@item @code{Ada.Text_IO} 20541 20542This package provides basic text input-output capabilities for 20543character, string and numeric data. The subpackages of this 20544package are listed next. Note that although these are defined 20545as subpackages in the RM, they are actually transparently 20546implemented as child packages in GNAT, meaning that they 20547are only loaded if needed. 20548 20549@item @code{Ada.Text_IO.Decimal_IO} 20550 20551Provides input-output facilities for decimal fixed-point types 20552 20553@item @code{Ada.Text_IO.Enumeration_IO} 20554 20555Provides input-output facilities for enumeration types. 20556 20557@item @code{Ada.Text_IO.Fixed_IO} 20558 20559Provides input-output facilities for ordinary fixed-point types. 20560 20561@item @code{Ada.Text_IO.Float_IO} 20562 20563Provides input-output facilities for float types. The following 20564predefined instantiations of this generic package are available: 20565 20566 20567@itemize * 20568 20569@item 20570@code{Short_Float} 20571 20572@cite{Short_Float_Text_IO} 20573 20574@item 20575@code{Float} 20576 20577@cite{Float_Text_IO} 20578 20579@item 20580@code{Long_Float} 20581 20582@cite{Long_Float_Text_IO} 20583@end itemize 20584 20585@item @code{Ada.Text_IO.Integer_IO} 20586 20587Provides input-output facilities for integer types. The following 20588predefined instantiations of this generic package are available: 20589 20590 20591@itemize * 20592 20593@item 20594@code{Short_Short_Integer} 20595 20596@cite{Ada.Short_Short_Integer_Text_IO} 20597 20598@item 20599@code{Short_Integer} 20600 20601@cite{Ada.Short_Integer_Text_IO} 20602 20603@item 20604@code{Integer} 20605 20606@cite{Ada.Integer_Text_IO} 20607 20608@item 20609@code{Long_Integer} 20610 20611@cite{Ada.Long_Integer_Text_IO} 20612 20613@item 20614@code{Long_Long_Integer} 20615 20616@cite{Ada.Long_Long_Integer_Text_IO} 20617@end itemize 20618 20619@item @code{Ada.Text_IO.Modular_IO} 20620 20621Provides input-output facilities for modular (unsigned) types. 20622 20623@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 20624 20625Provides input-output facilities for bounded strings. 20626 20627@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 20628 20629This package provides basic text input-output capabilities for complex 20630data. 20631 20632@item @code{Ada.Text_IO.Editing (F.3.3)} 20633 20634This package contains routines for edited output, analogous to the use 20635of pictures in COBOL. The picture formats used by this package are a 20636close copy of the facility in COBOL. 20637 20638@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 20639 20640This package provides a facility that allows Text_IO files to be treated 20641as streams, so that the stream attributes can be used for writing 20642arbitrary data, including binary data, to Text_IO files. 20643 20644@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 20645 20646This package provides input-output facilities for unbounded strings. 20647 20648@item @code{Ada.Unchecked_Conversion (13.9)} 20649 20650This generic package allows arbitrary conversion from one type to 20651another of the same size, providing for breaking the type safety in 20652special circumstances. 20653 20654If the types have the same Size (more accurately the same Value_Size), 20655then the effect is simply to transfer the bits from the source to the 20656target type without any modification. This usage is well defined, and 20657for simple types whose representation is typically the same across 20658all implementations, gives a portable method of performing such 20659conversions. 20660 20661If the types do not have the same size, then the result is implementation 20662defined, and thus may be non-portable. The following describes how GNAT 20663handles such unchecked conversion cases. 20664 20665If the types are of different sizes, and are both discrete types, then 20666the effect is of a normal type conversion without any constraint checking. 20667In particular if the result type has a larger size, the result will be 20668zero or sign extended. If the result type has a smaller size, the result 20669will be truncated by ignoring high order bits. 20670 20671If the types are of different sizes, and are not both discrete types, 20672then the conversion works as though pointers were created to the source 20673and target, and the pointer value is converted. The effect is that bits 20674are copied from successive low order storage units and bits of the source 20675up to the length of the target type. 20676 20677A warning is issued if the lengths differ, since the effect in this 20678case is implementation dependent, and the above behavior may not match 20679that of some other compiler. 20680 20681A pointer to one type may be converted to a pointer to another type using 20682unchecked conversion. The only case in which the effect is undefined is 20683when one or both pointers are pointers to unconstrained array types. In 20684this case, the bounds information may get incorrectly transferred, and in 20685particular, GNAT uses double size pointers for such types, and it is 20686meaningless to convert between such pointer types. GNAT will issue a 20687warning if the alignment of the target designated type is more strict 20688than the alignment of the source designated type (since the result may 20689be unaligned in this case). 20690 20691A pointer other than a pointer to an unconstrained array type may be 20692converted to and from System.Address. Such usage is common in Ada 83 20693programs, but note that Ada.Address_To_Access_Conversions is the 20694preferred method of performing such conversions in Ada 95 and Ada 2005. 20695Neither 20696unchecked conversion nor Ada.Address_To_Access_Conversions should be 20697used in conjunction with pointers to unconstrained objects, since 20698the bounds information cannot be handled correctly in this case. 20699 20700@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 20701 20702This generic package allows explicit freeing of storage previously 20703allocated by use of an allocator. 20704 20705@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 20706 20707This package is similar to @cite{Ada.Text_IO}, except that the external 20708file supports wide character representations, and the internal types are 20709@cite{Wide_Character} and @cite{Wide_String} instead of @cite{Character} 20710and @cite{String}. The corresponding set of nested packages and child 20711packages are defined. 20712 20713@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 20714 20715This package is similar to @cite{Ada.Text_IO}, except that the external 20716file supports wide character representations, and the internal types are 20717@cite{Wide_Character} and @cite{Wide_String} instead of @cite{Character} 20718and @cite{String}. The corresponding set of nested packages and child 20719packages are defined. 20720@end table 20721 20722For packages in Interfaces and System, all the RM defined packages are 20723available in GNAT, see the Ada 2012 RM for full details. 20724 20725@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 20726@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{253}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{254} 20727@chapter The Implementation of Standard I/O 20728 20729 20730GNAT implements all the required input-output facilities described in 20731A.6 through A.14. These sections of the Ada Reference Manual describe the 20732required behavior of these packages from the Ada point of view, and if 20733you are writing a portable Ada program that does not need to know the 20734exact manner in which Ada maps to the outside world when it comes to 20735reading or writing external files, then you do not need to read this 20736chapter. As long as your files are all regular files (not pipes or 20737devices), and as long as you write and read the files only from Ada, the 20738description in the Ada Reference Manual is sufficient. 20739 20740However, if you want to do input-output to pipes or other devices, such 20741as the keyboard or screen, or if the files you are dealing with are 20742either generated by some other language, or to be read by some other 20743language, then you need to know more about the details of how the GNAT 20744implementation of these input-output facilities behaves. 20745 20746In this chapter we give a detailed description of exactly how GNAT 20747interfaces to the file system. As always, the sources of the system are 20748available to you for answering questions at an even more detailed level, 20749but for most purposes the information in this chapter will suffice. 20750 20751Another reason that you may need to know more about how input-output is 20752implemented arises when you have a program written in mixed languages 20753where, for example, files are shared between the C and Ada sections of 20754the same program. GNAT provides some additional facilities, in the form 20755of additional child library packages, that facilitate this sharing, and 20756these additional facilities are also described in this chapter. 20757 20758@menu 20759* Standard I/O Packages:: 20760* FORM Strings:: 20761* Direct_IO:: 20762* Sequential_IO:: 20763* Text_IO:: 20764* Wide_Text_IO:: 20765* Wide_Wide_Text_IO:: 20766* Stream_IO:: 20767* Text Translation:: 20768* Shared Files:: 20769* Filenames encoding:: 20770* File content encoding:: 20771* Open Modes:: 20772* Operations on C Streams:: 20773* Interfacing to C Streams:: 20774 20775@end menu 20776 20777@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 20778@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{255}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{256} 20779@section Standard I/O Packages 20780 20781 20782The Standard I/O packages described in Annex A for 20783 20784 20785@itemize * 20786 20787@item 20788Ada.Text_IO 20789 20790@item 20791Ada.Text_IO.Complex_IO 20792 20793@item 20794Ada.Text_IO.Text_Streams 20795 20796@item 20797Ada.Wide_Text_IO 20798 20799@item 20800Ada.Wide_Text_IO.Complex_IO 20801 20802@item 20803Ada.Wide_Text_IO.Text_Streams 20804 20805@item 20806Ada.Wide_Wide_Text_IO 20807 20808@item 20809Ada.Wide_Wide_Text_IO.Complex_IO 20810 20811@item 20812Ada.Wide_Wide_Text_IO.Text_Streams 20813 20814@item 20815Ada.Stream_IO 20816 20817@item 20818Ada.Sequential_IO 20819 20820@item 20821Ada.Direct_IO 20822@end itemize 20823 20824are implemented using the C 20825library streams facility; where 20826 20827 20828@itemize * 20829 20830@item 20831All files are opened using @cite{fopen}. 20832 20833@item 20834All input/output operations use @cite{fread}/@cite{fwrite}. 20835@end itemize 20836 20837There is no internal buffering of any kind at the Ada library level. The only 20838buffering is that provided at the system level in the implementation of the 20839library routines that support streams. This facilitates shared use of these 20840streams by mixed language programs. Note though that system level buffering is 20841explicitly enabled at elaboration of the standard I/O packages and that can 20842have an impact on mixed language programs, in particular those using I/O before 20843calling the Ada elaboration routine (e.g., adainit). It is recommended to call 20844the Ada elaboration routine before performing any I/O or when impractical, 20845flush the common I/O streams and in particular Standard_Output before 20846elaborating the Ada code. 20847 20848@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 20849@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{257}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{258} 20850@section FORM Strings 20851 20852 20853The format of a FORM string in GNAT is: 20854 20855@example 20856"keyword=value,keyword=value,...,keyword=value" 20857@end example 20858 20859where letters may be in upper or lower case, and there are no spaces 20860between values. The order of the entries is not important. Currently 20861the following keywords defined. 20862 20863@example 20864TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 20865SHARED=[YES|NO] 20866WCEM=[n|h|u|s|e|8|b] 20867ENCODING=[UTF8|8BITS] 20868@end example 20869 20870The use of these parameters is described later in this section. If an 20871unrecognized keyword appears in a form string, it is silently ignored 20872and not considered invalid. 20873 20874@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 20875@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{259}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{25a} 20876@section Direct_IO 20877 20878 20879Direct_IO can only be instantiated for definite types. This is a 20880restriction of the Ada language, which means that the records are fixed 20881length (the length being determined by @code{type'Size}, rounded 20882up to the next storage unit boundary if necessary). 20883 20884The records of a Direct_IO file are simply written to the file in index 20885sequence, with the first record starting at offset zero, and subsequent 20886records following. There is no control information of any kind. For 20887example, if 32-bit integers are being written, each record takes 208884-bytes, so the record at index @cite{K} starts at offset 20889(@cite{K}-1)*4. 20890 20891There is no limit on the size of Direct_IO files, they are expanded as 20892necessary to accommodate whatever records are written to the file. 20893 20894@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 20895@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{25b}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{25c} 20896@section Sequential_IO 20897 20898 20899Sequential_IO may be instantiated with either a definite (constrained) 20900or indefinite (unconstrained) type. 20901 20902For the definite type case, the elements written to the file are simply 20903the memory images of the data values with no control information of any 20904kind. The resulting file should be read using the same type, no validity 20905checking is performed on input. 20906 20907For the indefinite type case, the elements written consist of two 20908parts. First is the size of the data item, written as the memory image 20909of a @cite{Interfaces.C.size_t} value, followed by the memory image of 20910the data value. The resulting file can only be read using the same 20911(unconstrained) type. Normal assignment checks are performed on these 20912read operations, and if these checks fail, @cite{Data_Error} is 20913raised. In particular, in the array case, the lengths must match, and in 20914the variant record case, if the variable for a particular read operation 20915is constrained, the discriminants must match. 20916 20917Note that it is not possible to use Sequential_IO to write variable 20918length array items, and then read the data back into different length 20919arrays. For example, the following will raise @cite{Data_Error}: 20920 20921@example 20922package IO is new Sequential_IO (String); 20923F : IO.File_Type; 20924S : String (1..4); 20925... 20926IO.Create (F) 20927IO.Write (F, "hello!") 20928IO.Reset (F, Mode=>In_File); 20929IO.Read (F, S); 20930Put_Line (S); 20931@end example 20932 20933On some Ada implementations, this will print @cite{hell}, but the program is 20934clearly incorrect, since there is only one element in the file, and that 20935element is the string @cite{hello!}. 20936 20937In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 20938using Stream_IO, and this is the preferred mechanism. In particular, the 20939above program fragment rewritten to use Stream_IO will work correctly. 20940 20941@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 20942@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{25d}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{25e} 20943@section Text_IO 20944 20945 20946Text_IO files consist of a stream of characters containing the following 20947special control characters: 20948 20949@example 20950LF (line feed, 16#0A#) Line Mark 20951FF (form feed, 16#0C#) Page Mark 20952@end example 20953 20954A canonical Text_IO file is defined as one in which the following 20955conditions are met: 20956 20957 20958@itemize * 20959 20960@item 20961The character @cite{LF} is used only as a line mark, i.e., to mark the end 20962of the line. 20963 20964@item 20965The character @cite{FF} is used only as a page mark, i.e., to mark the 20966end of a page and consequently can appear only immediately following a 20967@cite{LF} (line mark) character. 20968 20969@item 20970The file ends with either @cite{LF} (line mark) or @cite{LF}-@cite{FF} 20971(line mark, page mark). In the former case, the page mark is implicitly 20972assumed to be present. 20973@end itemize 20974 20975A file written using Text_IO will be in canonical form provided that no 20976explicit @cite{LF} or @cite{FF} characters are written using @cite{Put} 20977or @cite{Put_Line}. There will be no @cite{FF} character at the end of 20978the file unless an explicit @cite{New_Page} operation was performed 20979before closing the file. 20980 20981A canonical Text_IO file that is a regular file (i.e., not a device or a 20982pipe) can be read using any of the routines in Text_IO. The 20983semantics in this case will be exactly as defined in the Ada Reference 20984Manual, and all the routines in Text_IO are fully implemented. 20985 20986A text file that does not meet the requirements for a canonical Text_IO 20987file has one of the following: 20988 20989 20990@itemize * 20991 20992@item 20993The file contains @cite{FF} characters not immediately following a 20994@cite{LF} character. 20995 20996@item 20997The file contains @cite{LF} or @cite{FF} characters written by 20998@cite{Put} or @cite{Put_Line}, which are not logically considered to be 20999line marks or page marks. 21000 21001@item 21002The file ends in a character other than @cite{LF} or @cite{FF}, 21003i.e., there is no explicit line mark or page mark at the end of the file. 21004@end itemize 21005 21006Text_IO can be used to read such non-standard text files but subprograms 21007to do with line or page numbers do not have defined meanings. In 21008particular, a @cite{FF} character that does not follow a @cite{LF} 21009character may or may not be treated as a page mark from the point of 21010view of page and line numbering. Every @cite{LF} character is considered 21011to end a line, and there is an implied @cite{LF} character at the end of 21012the file. 21013 21014@menu 21015* Stream Pointer Positioning:: 21016* Reading and Writing Non-Regular Files:: 21017* Get_Immediate:: 21018* Treating Text_IO Files as Streams:: 21019* Text_IO Extensions:: 21020* Text_IO Facilities for Unbounded Strings:: 21021 21022@end menu 21023 21024@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21025@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{25f}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{260} 21026@subsection Stream Pointer Positioning 21027 21028 21029@cite{Ada.Text_IO} has a definition of current position for a file that 21030is being read. No internal buffering occurs in Text_IO, and usually the 21031physical position in the stream used to implement the file corresponds 21032to this logical position defined by Text_IO. There are two exceptions: 21033 21034 21035@itemize * 21036 21037@item 21038After a call to @cite{End_Of_Page} that returns @cite{True}, the stream 21039is positioned past the @cite{LF} (line mark) that precedes the page 21040mark. Text_IO maintains an internal flag so that subsequent read 21041operations properly handle the logical position which is unchanged by 21042the @cite{End_Of_Page} call. 21043 21044@item 21045After a call to @cite{End_Of_File} that returns @cite{True}, if the 21046Text_IO file was positioned before the line mark at the end of file 21047before the call, then the logical position is unchanged, but the stream 21048is physically positioned right at the end of file (past the line mark, 21049and past a possible page mark following the line mark. Again Text_IO 21050maintains internal flags so that subsequent read operations properly 21051handle the logical position. 21052@end itemize 21053 21054These discrepancies have no effect on the observable behavior of 21055Text_IO, but if a single Ada stream is shared between a C program and 21056Ada program, or shared (using @code{shared=yes} in the form string) 21057between two Ada files, then the difference may be observable in some 21058situations. 21059 21060@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21061@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{261}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{262} 21062@subsection Reading and Writing Non-Regular Files 21063 21064 21065A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21066can be used for reading and writing. Writing is not affected and the 21067sequence of characters output is identical to the normal file case, but 21068for reading, the behavior of Text_IO is modified to avoid undesirable 21069look-ahead as follows: 21070 21071An input file that is not a regular file is considered to have no page 21072marks. Any @cite{Ascii.FF} characters (the character normally used for a 21073page mark) appearing in the file are considered to be data 21074characters. In particular: 21075 21076 21077@itemize * 21078 21079@item 21080@cite{Get_Line} and @cite{Skip_Line} do not test for a page mark 21081following a line mark. If a page mark appears, it will be treated as a 21082data character. 21083 21084@item 21085This avoids the need to wait for an extra character to be typed or 21086entered from the pipe to complete one of these operations. 21087 21088@item 21089@cite{End_Of_Page} always returns @cite{False} 21090 21091@item 21092@cite{End_Of_File} will return @cite{False} if there is a page mark at 21093the end of the file. 21094@end itemize 21095 21096Output to non-regular files is the same as for regular files. Page marks 21097may be written to non-regular files using @cite{New_Page}, but as noted 21098above they will not be treated as page marks on input if the output is 21099piped to another Ada program. 21100 21101Another important discrepancy when reading non-regular files is that the end 21102of file indication is not 'sticky'. If an end of file is entered, e.g., by 21103pressing the @code{EOT} key, 21104then end of file 21105is signaled once (i.e., the test @cite{End_Of_File} 21106will yield @cite{True}, or a read will 21107raise @cite{End_Error}), but then reading can resume 21108to read data past that end of 21109file indication, until another end of file indication is entered. 21110 21111@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21112@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{263}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{264} 21113@subsection Get_Immediate 21114 21115 21116@geindex Get_Immediate 21117 21118Get_Immediate returns the next character (including control characters) 21119from the input file. In particular, Get_Immediate will return LF or FF 21120characters used as line marks or page marks. Such operations leave the 21121file positioned past the control character, and it is thus not treated 21122as having its normal function. This means that page, line and column 21123counts after this kind of Get_Immediate call are set as though the mark 21124did not occur. In the case where a Get_Immediate leaves the file 21125positioned between the line mark and page mark (which is not normally 21126possible), it is undefined whether the FF character will be treated as a 21127page mark. 21128 21129@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21130@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{265}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{266} 21131@subsection Treating Text_IO Files as Streams 21132 21133 21134@geindex Stream files 21135 21136The package @cite{Text_IO.Streams} allows a Text_IO file to be treated 21137as a stream. Data written to a Text_IO file in this stream mode is 21138binary data. If this binary data contains bytes 16#0A# (@cite{LF}) or 2113916#0C# (@cite{FF}), the resulting file may have non-standard 21140format. Similarly if read operations are used to read from a Text_IO 21141file treated as a stream, then @cite{LF} and @cite{FF} characters may be 21142skipped and the effect is similar to that described above for 21143@cite{Get_Immediate}. 21144 21145@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 21146@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{267}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{268} 21147@subsection Text_IO Extensions 21148 21149 21150@geindex Text_IO extensions 21151 21152A package GNAT.IO_Aux in the GNAT library provides some useful extensions 21153to the standard @cite{Text_IO} package: 21154 21155 21156@itemize * 21157 21158@item 21159function File_Exists (Name : String) return Boolean; 21160Determines if a file of the given name exists. 21161 21162@item 21163function Get_Line return String; 21164Reads a string from the standard input file. The value returned is exactly 21165the length of the line that was read. 21166 21167@item 21168function Get_Line (File : Ada.Text_IO.File_Type) return String; 21169Similar, except that the parameter File specifies the file from which 21170the string is to be read. 21171@end itemize 21172 21173@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 21174@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{269}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{26a} 21175@subsection Text_IO Facilities for Unbounded Strings 21176 21177 21178@geindex Text_IO for unbounded strings 21179 21180@geindex Unbounded_String 21181@geindex Text_IO operations 21182 21183The package @cite{Ada.Strings.Unbounded.Text_IO} 21184in library files @cite{a-suteio.ads/adb} contains some GNAT-specific 21185subprograms useful for Text_IO operations on unbounded strings: 21186 21187 21188@itemize * 21189 21190@item 21191function Get_Line (File : File_Type) return Unbounded_String; 21192Reads a line from the specified file 21193and returns the result as an unbounded string. 21194 21195@item 21196procedure Put (File : File_Type; U : Unbounded_String); 21197Writes the value of the given unbounded string to the specified file 21198Similar to the effect of 21199@cite{Put (To_String (U))} except that an extra copy is avoided. 21200 21201@item 21202procedure Put_Line (File : File_Type; U : Unbounded_String); 21203Writes the value of the given unbounded string to the specified file, 21204followed by a @cite{New_Line}. 21205Similar to the effect of @cite{Put_Line (To_String (U))} except 21206that an extra copy is avoided. 21207@end itemize 21208 21209In the above procedures, @cite{File} is of type @cite{Ada.Text_IO.File_Type} 21210and is optional. If the parameter is omitted, then the standard input or 21211output file is referenced as appropriate. 21212 21213The package @cite{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 21214files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 21215@cite{Wide_Text_IO} functionality for unbounded wide strings. 21216 21217The package @cite{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 21218files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 21219@cite{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 21220 21221@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 21222@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{26b}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{26c} 21223@section Wide_Text_IO 21224 21225 21226@cite{Wide_Text_IO} is similar in most respects to Text_IO, except that 21227both input and output files may contain special sequences that represent 21228wide character values. The encoding scheme for a given file may be 21229specified using a FORM parameter: 21230 21231@example 21232WCEM=`x` 21233@end example 21234 21235as part of the FORM string (WCEM = wide character encoding method), 21236where @cite{x} is one of the following characters 21237 21238 21239@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21240@headitem 21241 21242Character 21243 21244@tab 21245 21246Encoding 21247 21248@item 21249 21250@emph{h} 21251 21252@tab 21253 21254Hex ESC encoding 21255 21256@item 21257 21258@emph{u} 21259 21260@tab 21261 21262Upper half encoding 21263 21264@item 21265 21266@emph{s} 21267 21268@tab 21269 21270Shift-JIS encoding 21271 21272@item 21273 21274@emph{e} 21275 21276@tab 21277 21278EUC Encoding 21279 21280@item 21281 21282@emph{8} 21283 21284@tab 21285 21286UTF-8 encoding 21287 21288@item 21289 21290@emph{b} 21291 21292@tab 21293 21294Brackets encoding 21295 21296@end multitable 21297 21298 21299The encoding methods match those that 21300can be used in a source 21301program, but there is no requirement that the encoding method used for 21302the source program be the same as the encoding method used for files, 21303and different files may use different encoding methods. 21304 21305The default encoding method for the standard files, and for opened files 21306for which no WCEM parameter is given in the FORM string matches the 21307wide character encoding specified for the main program (the default 21308being brackets encoding if no coding method was specified with -gnatW). 21309 21310 21311@table @asis 21312 21313@item @emph{Hex Coding} 21314 21315In this encoding, a wide character is represented by a five character 21316sequence: 21317@end table 21318 21319@example 21320ESC a b c d 21321@end example 21322 21323 21324@quotation 21325 21326where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal 21327characters (using upper case letters) of the wide character code. For 21328example, ESC A345 is used to represent the wide character with code 2132916#A345#. This scheme is compatible with use of the full 21330@cite{Wide_Character} set. 21331@end quotation 21332 21333 21334@table @asis 21335 21336@item @emph{Upper Half Coding} 21337 21338The wide character with encoding 16#abcd#, where the upper bit is on 21339(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2134016#cd#. The second byte may never be a format control character, but is 21341not required to be in the upper half. This method can be also used for 21342shift-JIS or EUC where the internal coding matches the external coding. 21343 21344@item @emph{Shift JIS Coding} 21345 21346A wide character is represented by a two character sequence 16#ab# and 2134716#cd#, with the restrictions described for upper half encoding as 21348described above. The internal character code is the corresponding JIS 21349character according to the standard algorithm for Shift-JIS 21350conversion. Only characters defined in the JIS code set table can be 21351used with this encoding method. 21352 21353@item @emph{EUC Coding} 21354 21355A wide character is represented by a two character sequence 16#ab# and 2135616#cd#, with both characters being in the upper half. The internal 21357character code is the corresponding JIS character according to the EUC 21358encoding algorithm. Only characters defined in the JIS code set table 21359can be used with this encoding method. 21360 21361@item @emph{UTF-8 Coding} 21362 21363A wide character is represented using 21364UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2136510646-1/Am.2. Depending on the character value, the representation 21366is a one, two, or three byte sequence: 21367@end table 21368 21369@example 2137016#0000#-16#007f#: 2#0xxxxxxx# 2137116#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2137216#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 21373@end example 21374 21375 21376@quotation 21377 21378where the @cite{xxx} bits correspond to the left-padded bits of the 2137916-bit character value. Note that all lower half ASCII characters 21380are represented as ASCII bytes and all upper half characters and 21381other wide characters are represented as sequences of upper-half 21382(The full UTF-8 scheme allows for encoding 31-bit characters as 213836-byte sequences, but in this implementation, all UTF-8 sequences 21384of four or more bytes length will raise a Constraint_Error, as 21385will all invalid UTF-8 sequences.) 21386@end quotation 21387 21388 21389@table @asis 21390 21391@item @emph{Brackets Coding} 21392 21393In this encoding, a wide character is represented by the following eight 21394character sequence: 21395@end table 21396 21397@example 21398[ " a b c d " ] 21399@end example 21400 21401 21402@quotation 21403 21404where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal 21405characters (using uppercase letters) of the wide character code. For 21406example, @cite{["A345"]} is used to represent the wide character with code 21407@cite{16#A345#}. 21408This scheme is compatible with use of the full Wide_Character set. 21409On input, brackets coding can also be used for upper half characters, 21410e.g., @cite{["C1"]} for lower case a. However, on output, brackets notation 21411is only used for wide characters with a code greater than @cite{16#FF#}. 21412 21413Note that brackets coding is not normally used in the context of 21414Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 21415a portable way of encoding source files. In the context of Wide_Text_IO 21416or Wide_Wide_Text_IO, it can only be used if the file does not contain 21417any instance of the left bracket character other than to encode wide 21418character values using the brackets encoding method. In practice it is 21419expected that some standard wide character encoding method such 21420as UTF-8 will be used for text input output. 21421 21422If brackets notation is used, then any occurrence of a left bracket 21423in the input file which is not the start of a valid wide character 21424sequence will cause Constraint_Error to be raised. It is possible to 21425encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 21426input will interpret this as a left bracket. 21427 21428However, when a left bracket is output, it will be output as a left bracket 21429and not as ["5B"]. We make this decision because for normal use of 21430Wide_Text_IO for outputting messages, it is unpleasant to clobber left 21431brackets. For example, if we write: 21432 21433@example 21434Put_Line ("Start of output [first run]"); 21435@end example 21436 21437we really do not want to have the left bracket in this message clobbered so 21438that the output reads: 21439@end quotation 21440 21441@example 21442Start of output ["5B"]first run] 21443@end example 21444 21445 21446@quotation 21447 21448In practice brackets encoding is reasonably useful for normal Put_Line use 21449since we won't get confused between left brackets and wide character 21450sequences in the output. But for input, or when files are written out 21451and read back in, it really makes better sense to use one of the standard 21452encoding methods such as UTF-8. 21453@end quotation 21454 21455For the coding schemes other than UTF-8, Hex, or Brackets encoding, 21456not all wide character 21457values can be represented. An attempt to output a character that cannot 21458be represented using the encoding scheme for the file causes 21459Constraint_Error to be raised. An invalid wide character sequence on 21460input also causes Constraint_Error to be raised. 21461 21462@menu 21463* Stream Pointer Positioning: Stream Pointer Positioning<2>. 21464* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 21465 21466@end menu 21467 21468@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 21469@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{26d}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{26e} 21470@subsection Stream Pointer Positioning 21471 21472 21473@cite{Ada.Wide_Text_IO} is similar to @cite{Ada.Text_IO} in its handling 21474of stream pointer positioning (@ref{25e,,Text_IO}). There is one additional 21475case: 21476 21477If @cite{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 21478normal lower ASCII set (i.e., a character in the range: 21479 21480@example 21481Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 21482@end example 21483 21484then although the logical position of the file pointer is unchanged by 21485the @cite{Look_Ahead} call, the stream is physically positioned past the 21486wide character sequence. Again this is to avoid the need for buffering 21487or backup, and all @cite{Wide_Text_IO} routines check the internal 21488indication that this situation has occurred so that this is not visible 21489to a normal program using @cite{Wide_Text_IO}. However, this discrepancy 21490can be observed if the wide text file shares a stream with another file. 21491 21492@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 21493@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{26f}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{270} 21494@subsection Reading and Writing Non-Regular Files 21495 21496 21497As in the case of Text_IO, when a non-regular file is read, it is 21498assumed that the file contains no page marks (any form characters are 21499treated as data characters), and @cite{End_Of_Page} always returns 21500@cite{False}. Similarly, the end of file indication is not sticky, so 21501it is possible to read beyond an end of file. 21502 21503@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 21504@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{271}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{272} 21505@section Wide_Wide_Text_IO 21506 21507 21508@cite{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 21509both input and output files may contain special sequences that represent 21510wide wide character values. The encoding scheme for a given file may be 21511specified using a FORM parameter: 21512 21513@example 21514WCEM=`x` 21515@end example 21516 21517as part of the FORM string (WCEM = wide character encoding method), 21518where @cite{x} is one of the following characters 21519 21520 21521@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21522@headitem 21523 21524Character 21525 21526@tab 21527 21528Encoding 21529 21530@item 21531 21532@emph{h} 21533 21534@tab 21535 21536Hex ESC encoding 21537 21538@item 21539 21540@emph{u} 21541 21542@tab 21543 21544Upper half encoding 21545 21546@item 21547 21548@emph{s} 21549 21550@tab 21551 21552Shift-JIS encoding 21553 21554@item 21555 21556@emph{e} 21557 21558@tab 21559 21560EUC Encoding 21561 21562@item 21563 21564@emph{8} 21565 21566@tab 21567 21568UTF-8 encoding 21569 21570@item 21571 21572@emph{b} 21573 21574@tab 21575 21576Brackets encoding 21577 21578@end multitable 21579 21580 21581The encoding methods match those that 21582can be used in a source 21583program, but there is no requirement that the encoding method used for 21584the source program be the same as the encoding method used for files, 21585and different files may use different encoding methods. 21586 21587The default encoding method for the standard files, and for opened files 21588for which no WCEM parameter is given in the FORM string matches the 21589wide character encoding specified for the main program (the default 21590being brackets encoding if no coding method was specified with -gnatW). 21591 21592 21593@table @asis 21594 21595@item @emph{UTF-8 Coding} 21596 21597A wide character is represented using 21598UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2159910646-1/Am.2. Depending on the character value, the representation 21600is a one, two, three, or four byte sequence: 21601@end table 21602 21603@example 2160416#000000#-16#00007f#: 2#0xxxxxxx# 2160516#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2160616#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2160716#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 21608@end example 21609 21610 21611@quotation 21612 21613where the @cite{xxx} bits correspond to the left-padded bits of the 2161421-bit character value. Note that all lower half ASCII characters 21615are represented as ASCII bytes and all upper half characters and 21616other wide characters are represented as sequences of upper-half 21617characters. 21618@end quotation 21619 21620 21621@table @asis 21622 21623@item @emph{Brackets Coding} 21624 21625In this encoding, a wide wide character is represented by the following eight 21626character sequence if is in wide character range 21627@end table 21628 21629@example 21630[ " a b c d " ] 21631@end example 21632 21633 21634@quotation 21635 21636and by the following ten character sequence if not 21637@end quotation 21638 21639@example 21640[ " a b c d e f " ] 21641@end example 21642 21643 21644@quotation 21645 21646where @cite{a}, @cite{b}, @cite{c}, @cite{d}, @cite{e}, and @cite{f} 21647are the four or six hexadecimal 21648characters (using uppercase letters) of the wide wide character code. For 21649example, @cite{["01A345"]} is used to represent the wide wide character 21650with code @cite{16#01A345#}. 21651 21652This scheme is compatible with use of the full Wide_Wide_Character set. 21653On input, brackets coding can also be used for upper half characters, 21654e.g., @cite{["C1"]} for lower case a. However, on output, brackets notation 21655is only used for wide characters with a code greater than @cite{16#FF#}. 21656@end quotation 21657 21658If is also possible to use the other Wide_Character encoding methods, 21659such as Shift-JIS, but the other schemes cannot support the full range 21660of wide wide characters. 21661An attempt to output a character that cannot 21662be represented using the encoding scheme for the file causes 21663Constraint_Error to be raised. An invalid wide character sequence on 21664input also causes Constraint_Error to be raised. 21665 21666@menu 21667* Stream Pointer Positioning: Stream Pointer Positioning<3>. 21668* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 21669 21670@end menu 21671 21672@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 21673@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{273}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{274} 21674@subsection Stream Pointer Positioning 21675 21676 21677@cite{Ada.Wide_Wide_Text_IO} is similar to @cite{Ada.Text_IO} in its handling 21678of stream pointer positioning (@ref{25e,,Text_IO}). There is one additional 21679case: 21680 21681If @cite{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 21682normal lower ASCII set (i.e., a character in the range: 21683 21684@example 21685Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 21686@end example 21687 21688then although the logical position of the file pointer is unchanged by 21689the @cite{Look_Ahead} call, the stream is physically positioned past the 21690wide character sequence. Again this is to avoid the need for buffering 21691or backup, and all @cite{Wide_Wide_Text_IO} routines check the internal 21692indication that this situation has occurred so that this is not visible 21693to a normal program using @cite{Wide_Wide_Text_IO}. However, this discrepancy 21694can be observed if the wide text file shares a stream with another file. 21695 21696@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 21697@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{275}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{276} 21698@subsection Reading and Writing Non-Regular Files 21699 21700 21701As in the case of Text_IO, when a non-regular file is read, it is 21702assumed that the file contains no page marks (any form characters are 21703treated as data characters), and @cite{End_Of_Page} always returns 21704@cite{False}. Similarly, the end of file indication is not sticky, so 21705it is possible to read beyond an end of file. 21706 21707@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 21708@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{277}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{278} 21709@section Stream_IO 21710 21711 21712A stream file is a sequence of bytes, where individual elements are 21713written to the file as described in the Ada Reference Manual. The type 21714@cite{Stream_Element} is simply a byte. There are two ways to read or 21715write a stream file. 21716 21717 21718@itemize * 21719 21720@item 21721The operations @cite{Read} and @cite{Write} directly read or write a 21722sequence of stream elements with no control information. 21723 21724@item 21725The stream attributes applied to a stream file transfer data in the 21726manner described for stream attributes. 21727@end itemize 21728 21729@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 21730@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{279}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{27a} 21731@section Text Translation 21732 21733 21734@code{Text_Translation=xxx} may be used as the Form parameter 21735passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 21736has no effect on Unix systems. Possible values are: 21737 21738 21739@itemize * 21740 21741@item 21742@code{Yes} or @code{Text} is the default, which means to 21743translate LF to/from CR/LF on Windows systems. 21744 21745@code{No} disables this translation; i.e. it 21746uses binary mode. For output files, @code{Text_Translation=No} 21747may be used to create Unix-style files on 21748Windows. 21749 21750@item 21751@code{wtext} translation enabled in Unicode mode. 21752(corresponds to _O_WTEXT). 21753 21754@item 21755@code{u8text} translation enabled in Unicode UTF-8 mode. 21756(corresponds to O_U8TEXT). 21757 21758@item 21759@code{u16text} translation enabled in Unicode UTF-16 21760mode. (corresponds to_O_U16TEXT). 21761@end itemize 21762 21763@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 21764@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{27b}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{27c} 21765@section Shared Files 21766 21767 21768Section A.14 of the Ada Reference Manual allows implementations to 21769provide a wide variety of behavior if an attempt is made to access the 21770same external file with two or more internal files. 21771 21772To provide a full range of functionality, while at the same time 21773minimizing the problems of portability caused by this implementation 21774dependence, GNAT handles file sharing as follows: 21775 21776 21777@itemize * 21778 21779@item 21780In the absence of a @code{shared=xxx} form parameter, an attempt 21781to open two or more files with the same full name is considered an error 21782and is not supported. The exception @cite{Use_Error} will be 21783raised. Note that a file that is not explicitly closed by the program 21784remains open until the program terminates. 21785 21786@item 21787If the form parameter @code{shared=no} appears in the form string, the 21788file can be opened or created with its own separate stream identifier, 21789regardless of whether other files sharing the same external file are 21790opened. The exact effect depends on how the C stream routines handle 21791multiple accesses to the same external files using separate streams. 21792 21793@item 21794If the form parameter @code{shared=yes} appears in the form string for 21795each of two or more files opened using the same full name, the same 21796stream is shared between these files, and the semantics are as described 21797in Ada Reference Manual, Section A.14. 21798@end itemize 21799 21800When a program that opens multiple files with the same name is ported 21801from another Ada compiler to GNAT, the effect will be that 21802@cite{Use_Error} is raised. 21803 21804The documentation of the original compiler and the documentation of the 21805program should then be examined to determine if file sharing was 21806expected, and @code{shared=xxx} parameters added to @cite{Open} 21807and @cite{Create} calls as required. 21808 21809When a program is ported from GNAT to some other Ada compiler, no 21810special attention is required unless the @code{shared=xxx} form 21811parameter is used in the program. In this case, you must examine the 21812documentation of the new compiler to see if it supports the required 21813file sharing semantics, and form strings modified appropriately. Of 21814course it may be the case that the program cannot be ported if the 21815target compiler does not support the required functionality. The best 21816approach in writing portable code is to avoid file sharing (and hence 21817the use of the @code{shared=xxx} parameter in the form string) 21818completely. 21819 21820One common use of file sharing in Ada 83 is the use of instantiations of 21821Sequential_IO on the same file with different types, to achieve 21822heterogeneous input-output. Although this approach will work in GNAT if 21823@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 21824for this purpose (using the stream attributes) 21825 21826@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 21827@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{27d}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{27e} 21828@section Filenames encoding 21829 21830 21831An encoding form parameter can be used to specify the filename 21832encoding @code{encoding=xxx}. 21833 21834 21835@itemize * 21836 21837@item 21838If the form parameter @code{encoding=utf8} appears in the form string, the 21839filename must be encoded in UTF-8. 21840 21841@item 21842If the form parameter @code{encoding=8bits} appears in the form 21843string, the filename must be a standard 8bits string. 21844@end itemize 21845 21846In the absence of a @code{encoding=xxx} form parameter, the 21847encoding is controlled by the @code{GNAT_CODE_PAGE} environment 21848variable. And if not set @code{utf8} is assumed. 21849 21850 21851@table @asis 21852 21853@item @emph{CP_ACP} 21854 21855The current system Windows ANSI code page. 21856 21857@item @emph{CP_UTF8} 21858 21859UTF-8 encoding 21860@end table 21861 21862This encoding form parameter is only supported on the Windows 21863platform. On the other Operating Systems the run-time is supporting 21864UTF-8 natively. 21865 21866@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 21867@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{27f}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{280} 21868@section File content encoding 21869 21870 21871For text files it is possible to specify the encoding to use. This is 21872controlled by the by the @code{GNAT_CCS_ENCODING} environment 21873variable. And if not set @code{TEXT} is assumed. 21874 21875The possible values are those supported on Windows: 21876 21877 21878@table @asis 21879 21880@item @emph{TEXT} 21881 21882Translated text mode 21883 21884@item @emph{WTEXT} 21885 21886Translated unicode encoding 21887 21888@item @emph{U16TEXT} 21889 21890Unicode 16-bit encoding 21891 21892@item @emph{U8TEXT} 21893 21894Unicode 8-bit encoding 21895@end table 21896 21897This encoding is only supported on the Windows platform. 21898 21899@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 21900@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{281}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{282} 21901@section Open Modes 21902 21903 21904@cite{Open} and @cite{Create} calls result in a call to @cite{fopen} 21905using the mode shown in the following table: 21906 21907 21908@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 21909@headitem 21910 21911@cite{Open} and @cite{Create} Call Modes 21912 21913@tab 21914 21915@tab 21916 21917@item 21918 21919@tab 21920 21921@strong{OPEN} 21922 21923@tab 21924 21925@strong{CREATE} 21926 21927@item 21928 21929Append_File 21930 21931@tab 21932 21933"r+" 21934 21935@tab 21936 21937"w+" 21938 21939@item 21940 21941In_File 21942 21943@tab 21944 21945"r" 21946 21947@tab 21948 21949"w+" 21950 21951@item 21952 21953Out_File (Direct_IO) 21954 21955@tab 21956 21957"r+" 21958 21959@tab 21960 21961"w" 21962 21963@item 21964 21965Out_File (all other cases) 21966 21967@tab 21968 21969"w" 21970 21971@tab 21972 21973"w" 21974 21975@item 21976 21977Inout_File 21978 21979@tab 21980 21981"r+" 21982 21983@tab 21984 21985"w+" 21986 21987@end multitable 21988 21989 21990If text file translation is required, then either @code{b} or @code{t} 21991is added to the mode, depending on the setting of Text. Text file 21992translation refers to the mapping of CR/LF sequences in an external file 21993to LF characters internally. This mapping only occurs in DOS and 21994DOS-like systems, and is not relevant to other systems. 21995 21996A special case occurs with Stream_IO. As shown in the above table, the 21997file is initially opened in @code{r} or @code{w} mode for the 21998@cite{In_File} and @cite{Out_File} cases. If a @cite{Set_Mode} operation 21999subsequently requires switching from reading to writing or vice-versa, 22000then the file is reopened in @code{r+} mode to permit the required operation. 22001 22002@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22003@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{283}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{284} 22004@section Operations on C Streams 22005 22006 22007The package @cite{Interfaces.C_Streams} provides an Ada program with direct 22008access to the C library functions for operations on C streams: 22009 22010@example 22011package Interfaces.C_Streams is 22012 -- Note: the reason we do not use the types that are in 22013 -- Interfaces.C is that we want to avoid dragging in the 22014 -- code in this unit if possible. 22015 subtype chars is System.Address; 22016 -- Pointer to null-terminated array of characters 22017 subtype FILEs is System.Address; 22018 -- Corresponds to the C type FILE* 22019 subtype voids is System.Address; 22020 -- Corresponds to the C type void* 22021 subtype int is Integer; 22022 subtype long is Long_Integer; 22023 -- Note: the above types are subtypes deliberately, and it 22024 -- is part of this spec that the above correspondences are 22025 -- guaranteed. This means that it is legitimate to, for 22026 -- example, use Integer instead of int. We provide these 22027 -- synonyms for clarity, but in some cases it may be 22028 -- convenient to use the underlying types (for example to 22029 -- avoid an unnecessary dependency of a spec on the spec 22030 -- of this unit). 22031 type size_t is mod 2 ** Standard'Address_Size; 22032 NULL_Stream : constant FILEs; 22033 -- Value returned (NULL in C) to indicate an 22034 -- fdopen/fopen/tmpfile error 22035 ---------------------------------- 22036 -- Constants Defined in stdio.h -- 22037 ---------------------------------- 22038 EOF : constant int; 22039 -- Used by a number of routines to indicate error or 22040 -- end of file 22041 IOFBF : constant int; 22042 IOLBF : constant int; 22043 IONBF : constant int; 22044 -- Used to indicate buffering mode for setvbuf call 22045 SEEK_CUR : constant int; 22046 SEEK_END : constant int; 22047 SEEK_SET : constant int; 22048 -- Used to indicate origin for fseek call 22049 function stdin return FILEs; 22050 function stdout return FILEs; 22051 function stderr return FILEs; 22052 -- Streams associated with standard files 22053 -------------------------- 22054 -- Standard C functions -- 22055 -------------------------- 22056 -- The functions selected below are ones that are 22057 -- available in UNIX (but not necessarily in ANSI C). 22058 -- These are very thin interfaces 22059 -- which copy exactly the C headers. For more 22060 -- documentation on these functions, see the Microsoft C 22061 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22062 -- ISBN 1-55615-225-6), which includes useful information 22063 -- on system compatibility. 22064 procedure clearerr (stream : FILEs); 22065 function fclose (stream : FILEs) return int; 22066 function fdopen (handle : int; mode : chars) return FILEs; 22067 function feof (stream : FILEs) return int; 22068 function ferror (stream : FILEs) return int; 22069 function fflush (stream : FILEs) return int; 22070 function fgetc (stream : FILEs) return int; 22071 function fgets (strng : chars; n : int; stream : FILEs) 22072 return chars; 22073 function fileno (stream : FILEs) return int; 22074 function fopen (filename : chars; Mode : chars) 22075 return FILEs; 22076 -- Note: to maintain target independence, use 22077 -- text_translation_required, a boolean variable defined in 22078 -- a-sysdep.c to deal with the target dependent text 22079 -- translation requirement. If this variable is set, 22080 -- then b/t should be appended to the standard mode 22081 -- argument to set the text translation mode off or on 22082 -- as required. 22083 function fputc (C : int; stream : FILEs) return int; 22084 function fputs (Strng : chars; Stream : FILEs) return int; 22085 function fread 22086 (buffer : voids; 22087 size : size_t; 22088 count : size_t; 22089 stream : FILEs) 22090 return size_t; 22091 function freopen 22092 (filename : chars; 22093 mode : chars; 22094 stream : FILEs) 22095 return FILEs; 22096 function fseek 22097 (stream : FILEs; 22098 offset : long; 22099 origin : int) 22100 return int; 22101 function ftell (stream : FILEs) return long; 22102 function fwrite 22103 (buffer : voids; 22104 size : size_t; 22105 count : size_t; 22106 stream : FILEs) 22107 return size_t; 22108 function isatty (handle : int) return int; 22109 procedure mktemp (template : chars); 22110 -- The return value (which is just a pointer to template) 22111 -- is discarded 22112 procedure rewind (stream : FILEs); 22113 function rmtmp return int; 22114 function setvbuf 22115 (stream : FILEs; 22116 buffer : chars; 22117 mode : int; 22118 size : size_t) 22119 return int; 22120 22121 function tmpfile return FILEs; 22122 function ungetc (c : int; stream : FILEs) return int; 22123 function unlink (filename : chars) return int; 22124 --------------------- 22125 -- Extra functions -- 22126 --------------------- 22127 -- These functions supply slightly thicker bindings than 22128 -- those above. They are derived from functions in the 22129 -- C Run-Time Library, but may do a bit more work than 22130 -- just directly calling one of the Library functions. 22131 function is_regular_file (handle : int) return int; 22132 -- Tests if given handle is for a regular file (result 1) 22133 -- or for a non-regular file (pipe or device, result 0). 22134 --------------------------------- 22135 -- Control of Text/Binary Mode -- 22136 --------------------------------- 22137 -- If text_translation_required is true, then the following 22138 -- functions may be used to dynamically switch a file from 22139 -- binary to text mode or vice versa. These functions have 22140 -- no effect if text_translation_required is false (i.e., in 22141 -- normal UNIX mode). Use fileno to get a stream handle. 22142 procedure set_binary_mode (handle : int); 22143 procedure set_text_mode (handle : int); 22144 ---------------------------- 22145 -- Full Path Name support -- 22146 ---------------------------- 22147 procedure full_name (nam : chars; buffer : chars); 22148 -- Given a NUL terminated string representing a file 22149 -- name, returns in buffer a NUL terminated string 22150 -- representing the full path name for the file name. 22151 -- On systems where it is relevant the drive is also 22152 -- part of the full path name. It is the responsibility 22153 -- of the caller to pass an actual parameter for buffer 22154 -- that is big enough for any full path name. Use 22155 -- max_path_len given below as the size of buffer. 22156 max_path_len : integer; 22157 -- Maximum length of an allowable full path name on the 22158 -- system, including a terminating NUL character. 22159end Interfaces.C_Streams; 22160@end example 22161 22162@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 22163@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{285}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{286} 22164@section Interfacing to C Streams 22165 22166 22167The packages in this section permit interfacing Ada files to C Stream 22168operations. 22169 22170@example 22171with Interfaces.C_Streams; 22172package Ada.Sequential_IO.C_Streams is 22173 function C_Stream (F : File_Type) 22174 return Interfaces.C_Streams.FILEs; 22175 procedure Open 22176 (File : in out File_Type; 22177 Mode : in File_Mode; 22178 C_Stream : in Interfaces.C_Streams.FILEs; 22179 Form : in String := ""); 22180end Ada.Sequential_IO.C_Streams; 22181 22182 with Interfaces.C_Streams; 22183 package Ada.Direct_IO.C_Streams is 22184 function C_Stream (F : File_Type) 22185 return Interfaces.C_Streams.FILEs; 22186 procedure Open 22187 (File : in out File_Type; 22188 Mode : in File_Mode; 22189 C_Stream : in Interfaces.C_Streams.FILEs; 22190 Form : in String := ""); 22191 end Ada.Direct_IO.C_Streams; 22192 22193 with Interfaces.C_Streams; 22194 package Ada.Text_IO.C_Streams is 22195 function C_Stream (F : File_Type) 22196 return Interfaces.C_Streams.FILEs; 22197 procedure Open 22198 (File : in out File_Type; 22199 Mode : in File_Mode; 22200 C_Stream : in Interfaces.C_Streams.FILEs; 22201 Form : in String := ""); 22202 end Ada.Text_IO.C_Streams; 22203 22204 with Interfaces.C_Streams; 22205 package Ada.Wide_Text_IO.C_Streams is 22206 function C_Stream (F : File_Type) 22207 return Interfaces.C_Streams.FILEs; 22208 procedure Open 22209 (File : in out File_Type; 22210 Mode : in File_Mode; 22211 C_Stream : in Interfaces.C_Streams.FILEs; 22212 Form : in String := ""); 22213end Ada.Wide_Text_IO.C_Streams; 22214 22215 with Interfaces.C_Streams; 22216 package Ada.Wide_Wide_Text_IO.C_Streams is 22217 function C_Stream (F : File_Type) 22218 return Interfaces.C_Streams.FILEs; 22219 procedure Open 22220 (File : in out File_Type; 22221 Mode : in File_Mode; 22222 C_Stream : in Interfaces.C_Streams.FILEs; 22223 Form : in String := ""); 22224end Ada.Wide_Wide_Text_IO.C_Streams; 22225 22226with Interfaces.C_Streams; 22227package Ada.Stream_IO.C_Streams is 22228 function C_Stream (F : File_Type) 22229 return Interfaces.C_Streams.FILEs; 22230 procedure Open 22231 (File : in out File_Type; 22232 Mode : in File_Mode; 22233 C_Stream : in Interfaces.C_Streams.FILEs; 22234 Form : in String := ""); 22235end Ada.Stream_IO.C_Streams; 22236@end example 22237 22238In each of these six packages, the @cite{C_Stream} function obtains the 22239@cite{FILE} pointer from a currently opened Ada file. It is then 22240possible to use the @cite{Interfaces.C_Streams} package to operate on 22241this stream, or the stream can be passed to a C program which can 22242operate on it directly. Of course the program is responsible for 22243ensuring that only appropriate sequences of operations are executed. 22244 22245One particular use of relevance to an Ada program is that the 22246@cite{setvbuf} function can be used to control the buffering of the 22247stream used by an Ada file. In the absence of such a call the standard 22248default buffering is used. 22249 22250The @cite{Open} procedures in these packages open a file giving an 22251existing C Stream instead of a file name. Typically this stream is 22252imported from a C program, allowing an Ada file to operate on an 22253existing C file. 22254 22255@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 22256@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{287}@anchor{gnat_rm/the_gnat_library id1}@anchor{288} 22257@chapter The GNAT Library 22258 22259 22260The GNAT library contains a number of general and special purpose packages. 22261It represents functionality that the GNAT developers have found useful, and 22262which is made available to GNAT users. The packages described here are fully 22263supported, and upwards compatibility will be maintained in future releases, 22264so you can use these facilities with the confidence that the same functionality 22265will be available in future releases. 22266 22267The chapter here simply gives a brief summary of the facilities available. 22268The full documentation is found in the spec file for the package. The full 22269sources of these library packages, including both spec and body, are provided 22270with all GNAT releases. For example, to find out the full specifications of 22271the SPITBOL pattern matching capability, including a full tutorial and 22272extensive examples, look in the @code{g-spipat.ads} file in the library. 22273 22274For each entry here, the package name (as it would appear in a @cite{with} 22275clause) is given, followed by the name of the corresponding spec file in 22276parentheses. The packages are children in four hierarchies, @cite{Ada}, 22277@cite{Interfaces}, @cite{System}, and @cite{GNAT}, the latter being a 22278GNAT-specific hierarchy. 22279 22280Note that an application program should only use packages in one of these 22281four hierarchies if the package is defined in the Ada Reference Manual, 22282or is listed in this section of the GNAT Programmers Reference Manual. 22283All other units should be considered internal implementation units and 22284should not be directly @cite{with}'ed by application code. The use of 22285a @cite{with} statement that references one of these internal implementation 22286units makes an application potentially dependent on changes in versions 22287of GNAT, and will generate a warning message. 22288 22289@menu 22290* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 22291* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 22292* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 22293* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 22294* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 22295* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 22296* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 22297* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 22298* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 22299* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 22300* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 22301* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 22302* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 22303* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 22304* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 22305* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 22306* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 22307* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 22308* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 22309* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 22310* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 22311* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 22312* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 22313* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 22314* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 22315* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 22316* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 22317* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 22318* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 22319* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 22320* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 22321* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 22322* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 22323* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 22324* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 22325* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 22326* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 22327* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 22328* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 22329* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 22330* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 22331* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 22332* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 22333* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 22334* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 22335* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 22336* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 22337* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 22338* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 22339* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 22340* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 22341* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 22342* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 22343* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 22344* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 22345* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 22346* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 22347* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 22348* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 22349* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 22350* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 22351* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 22352* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 22353* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 22354* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 22355* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 22356* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 22357* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 22358* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 22359* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 22360* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 22361* GNAT.Exceptions (g-expect.ads): GNAT Exceptions g-expect ads. 22362* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 22363* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 22364* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 22365* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 22366* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 22367* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 22368* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 22369* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 22370* GNAT.IO (g-io.ads): GNAT IO g-io ads. 22371* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 22372* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 22373* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 22374* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 22375* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 22376* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 22377* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 22378* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 22379* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 22380* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 22381* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 22382* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 22383* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 22384* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 22385* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 22386* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 22387* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 22388* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 22389* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 22390* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 22391* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 22392* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 22393* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 22394* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 22395* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 22396* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 22397* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 22398* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 22399* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 22400* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 22401* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 22402* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 22403* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 22404* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 22405* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 22406* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 22407* GNAT.Table (g-table.ads): GNAT Table g-table ads. 22408* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 22409* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 22410* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 22411* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 22412* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 22413* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 22414* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 22415* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 22416* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 22417* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 22418* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 22419* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 22420* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 22421* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 22422* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 22423* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 22424* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 22425* System.Assertions (s-assert.ads): System Assertions s-assert ads. 22426* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 22427* System.Memory (s-memory.ads): System Memory s-memory ads. 22428* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 22429* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 22430* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 22431* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 22432* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 22433* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 22434* System.Rident (s-rident.ads): System Rident s-rident ads. 22435* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 22436* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 22437* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 22438* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 22439 22440@end menu 22441 22442@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 22443@anchor{gnat_rm/the_gnat_library id2}@anchor{289}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{28a} 22444@section @cite{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 22445 22446 22447@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 22448 22449@geindex Latin_9 constants for Character 22450 22451This child of @cite{Ada.Characters} 22452provides a set of definitions corresponding to those in the 22453RM-defined package @cite{Ada.Characters.Latin_1} but with the 22454few modifications required for @cite{Latin-9} 22455The provision of such a package 22456is specifically authorized by the Ada Reference Manual 22457(RM A.3.3(27)). 22458 22459@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 22460@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{28b}@anchor{gnat_rm/the_gnat_library id3}@anchor{28c} 22461@section @cite{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 22462 22463 22464@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 22465 22466@geindex Latin_1 constants for Wide_Character 22467 22468This child of @cite{Ada.Characters} 22469provides a set of definitions corresponding to those in the 22470RM-defined package @cite{Ada.Characters.Latin_1} but with the 22471types of the constants being @cite{Wide_Character} 22472instead of @cite{Character}. The provision of such a package 22473is specifically authorized by the Ada Reference Manual 22474(RM A.3.3(27)). 22475 22476@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 22477@anchor{gnat_rm/the_gnat_library id4}@anchor{28d}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{28e} 22478@section @cite{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 22479 22480 22481@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 22482 22483@geindex Latin_9 constants for Wide_Character 22484 22485This child of @cite{Ada.Characters} 22486provides a set of definitions corresponding to those in the 22487GNAT defined package @cite{Ada.Characters.Latin_9} but with the 22488types of the constants being @cite{Wide_Character} 22489instead of @cite{Character}. The provision of such a package 22490is specifically authorized by the Ada Reference Manual 22491(RM A.3.3(27)). 22492 22493@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 22494@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{28f}@anchor{gnat_rm/the_gnat_library id5}@anchor{290} 22495@section @cite{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 22496 22497 22498@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 22499 22500@geindex Latin_1 constants for Wide_Wide_Character 22501 22502This child of @cite{Ada.Characters} 22503provides a set of definitions corresponding to those in the 22504RM-defined package @cite{Ada.Characters.Latin_1} but with the 22505types of the constants being @cite{Wide_Wide_Character} 22506instead of @cite{Character}. The provision of such a package 22507is specifically authorized by the Ada Reference Manual 22508(RM A.3.3(27)). 22509 22510@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 22511@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{291}@anchor{gnat_rm/the_gnat_library id6}@anchor{292} 22512@section @cite{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 22513 22514 22515@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 22516 22517@geindex Latin_9 constants for Wide_Wide_Character 22518 22519This child of @cite{Ada.Characters} 22520provides a set of definitions corresponding to those in the 22521GNAT defined package @cite{Ada.Characters.Latin_9} but with the 22522types of the constants being @cite{Wide_Wide_Character} 22523instead of @cite{Character}. The provision of such a package 22524is specifically authorized by the Ada Reference Manual 22525(RM A.3.3(27)). 22526 22527@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 22528@anchor{gnat_rm/the_gnat_library id7}@anchor{293}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{294} 22529@section @cite{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 22530 22531 22532@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 22533 22534@geindex Formal container for doubly linked lists 22535 22536This child of @cite{Ada.Containers} defines a modified version of the 22537Ada 2005 container for doubly linked lists, meant to facilitate formal 22538verification of code using such containers. The specification of this 22539unit is compatible with SPARK 2014. 22540 22541Note that although this container was designed with formal verification 22542in mind, it may well be generally useful in that it is a simplified more 22543efficient version than the one defined in the standard. In particular it 22544does not have the complex overhead required to detect cursor tampering. 22545 22546@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 22547@anchor{gnat_rm/the_gnat_library id8}@anchor{295}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{296} 22548@section @cite{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 22549 22550 22551@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 22552 22553@geindex Formal container for hashed maps 22554 22555This child of @cite{Ada.Containers} defines a modified version of the 22556Ada 2005 container for hashed maps, meant to facilitate formal 22557verification of code using such containers. The specification of this 22558unit is compatible with SPARK 2014. 22559 22560Note that although this container was designed with formal verification 22561in mind, it may well be generally useful in that it is a simplified more 22562efficient version than the one defined in the standard. In particular it 22563does not have the complex overhead required to detect cursor tampering. 22564 22565@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 22566@anchor{gnat_rm/the_gnat_library id9}@anchor{297}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{298} 22567@section @cite{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 22568 22569 22570@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 22571 22572@geindex Formal container for hashed sets 22573 22574This child of @cite{Ada.Containers} defines a modified version of the 22575Ada 2005 container for hashed sets, meant to facilitate formal 22576verification of code using such containers. The specification of this 22577unit is compatible with SPARK 2014. 22578 22579Note that although this container was designed with formal verification 22580in mind, it may well be generally useful in that it is a simplified more 22581efficient version than the one defined in the standard. In particular it 22582does not have the complex overhead required to detect cursor tampering. 22583 22584@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 22585@anchor{gnat_rm/the_gnat_library id10}@anchor{299}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{29a} 22586@section @cite{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 22587 22588 22589@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 22590 22591@geindex Formal container for ordered maps 22592 22593This child of @cite{Ada.Containers} defines a modified version of the 22594Ada 2005 container for ordered maps, meant to facilitate formal 22595verification of code using such containers. The specification of this 22596unit is compatible with SPARK 2014. 22597 22598Note that although this container was designed with formal verification 22599in mind, it may well be generally useful in that it is a simplified more 22600efficient version than the one defined in the standard. In particular it 22601does not have the complex overhead required to detect cursor tampering. 22602 22603@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 22604@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{29b}@anchor{gnat_rm/the_gnat_library id11}@anchor{29c} 22605@section @cite{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 22606 22607 22608@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 22609 22610@geindex Formal container for ordered sets 22611 22612This child of @cite{Ada.Containers} defines a modified version of the 22613Ada 2005 container for ordered sets, meant to facilitate formal 22614verification of code using such containers. The specification of this 22615unit is compatible with SPARK 2014. 22616 22617Note that although this container was designed with formal verification 22618in mind, it may well be generally useful in that it is a simplified more 22619efficient version than the one defined in the standard. In particular it 22620does not have the complex overhead required to detect cursor tampering. 22621 22622@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 22623@anchor{gnat_rm/the_gnat_library id12}@anchor{29d}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{29e} 22624@section @cite{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 22625 22626 22627@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 22628 22629@geindex Formal container for vectors 22630 22631This child of @cite{Ada.Containers} defines a modified version of the 22632Ada 2005 container for vectors, meant to facilitate formal 22633verification of code using such containers. The specification of this 22634unit is compatible with SPARK 2014. 22635 22636Note that although this container was designed with formal verification 22637in mind, it may well be generally useful in that it is a simplified more 22638efficient version than the one defined in the standard. In particular it 22639does not have the complex overhead required to detect cursor tampering. 22640 22641@node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library 22642@anchor{gnat_rm/the_gnat_library id13}@anchor{29f}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2a0} 22643@section @cite{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 22644 22645 22646@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 22647 22648@geindex Formal container for vectors 22649 22650This child of @cite{Ada.Containers} defines a modified version of the 22651Ada 2005 container for vectors of indefinite elements, meant to 22652facilitate formal verification of code using such containers. The 22653specification of this unit is compatible with SPARK 2014. 22654 22655Note that although this container was designed with formal verification 22656in mind, it may well be generally useful in that it is a simplified more 22657efficient version than the one defined in the standard. In particular it 22658does not have the complex overhead required to detect cursor tampering. 22659 22660@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library 22661@anchor{gnat_rm/the_gnat_library id14}@anchor{2a1}@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2a2} 22662@section @cite{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 22663 22664 22665@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 22666 22667@geindex Formal container for vectors 22668 22669This child of @cite{Ada.Containers} defines a modified version of 22670Indefinite_Holders that avoids heap allocation. 22671 22672@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 22673@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2a3}@anchor{gnat_rm/the_gnat_library id15}@anchor{2a4} 22674@section @cite{Ada.Command_Line.Environment} (@code{a-colien.ads}) 22675 22676 22677@geindex Ada.Command_Line.Environment (a-colien.ads) 22678 22679@geindex Environment entries 22680 22681This child of @cite{Ada.Command_Line} 22682provides a mechanism for obtaining environment values on systems 22683where this concept makes sense. 22684 22685@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 22686@anchor{gnat_rm/the_gnat_library id16}@anchor{2a5}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2a6} 22687@section @cite{Ada.Command_Line.Remove} (@code{a-colire.ads}) 22688 22689 22690@geindex Ada.Command_Line.Remove (a-colire.ads) 22691 22692@geindex Removing command line arguments 22693 22694@geindex Command line 22695@geindex argument removal 22696 22697This child of @cite{Ada.Command_Line} 22698provides a mechanism for logically removing 22699arguments from the argument list. Once removed, an argument is not visible 22700to further calls on the subprograms in @cite{Ada.Command_Line} will not 22701see the removed argument. 22702 22703@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 22704@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2a7}@anchor{gnat_rm/the_gnat_library id17}@anchor{2a8} 22705@section @cite{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 22706 22707 22708@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 22709 22710@geindex Response file for command line 22711 22712@geindex Command line 22713@geindex response file 22714 22715@geindex Command line 22716@geindex handling long command lines 22717 22718This child of @cite{Ada.Command_Line} provides a mechanism facilities for 22719getting command line arguments from a text file, called a "response file". 22720Using a response file allow passing a set of arguments to an executable longer 22721than the maximum allowed by the system on the command line. 22722 22723@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 22724@anchor{gnat_rm/the_gnat_library id18}@anchor{2a9}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2aa} 22725@section @cite{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 22726 22727 22728@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 22729 22730@geindex C Streams 22731@geindex Interfacing with Direct_IO 22732 22733This package provides subprograms that allow interfacing between 22734C streams and @cite{Direct_IO}. The stream identifier can be 22735extracted from a file opened on the Ada side, and an Ada file 22736can be constructed from a stream opened on the C side. 22737 22738@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 22739@anchor{gnat_rm/the_gnat_library id19}@anchor{2ab}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2ac} 22740@section @cite{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 22741 22742 22743@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 22744 22745@geindex Null_Occurrence 22746@geindex testing for 22747 22748This child subprogram provides a way of testing for the null 22749exception occurrence (@cite{Null_Occurrence}) without raising 22750an exception. 22751 22752@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 22753@anchor{gnat_rm/the_gnat_library id20}@anchor{2ad}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ae} 22754@section @cite{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 22755 22756 22757@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 22758 22759@geindex Null_Occurrence 22760@geindex testing for 22761 22762This child subprogram is used for handling otherwise unhandled 22763exceptions (hence the name last chance), and perform clean ups before 22764terminating the program. Note that this subprogram never returns. 22765 22766@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 22767@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2af}@anchor{gnat_rm/the_gnat_library id21}@anchor{2b0} 22768@section @cite{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 22769 22770 22771@geindex Ada.Exceptions.Traceback (a-exctra.ads) 22772 22773@geindex Traceback for Exception Occurrence 22774 22775This child package provides the subprogram (@cite{Tracebacks}) to 22776give a traceback array of addresses based on an exception 22777occurrence. 22778 22779@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 22780@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2b1}@anchor{gnat_rm/the_gnat_library id22}@anchor{2b2} 22781@section @cite{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 22782 22783 22784@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 22785 22786@geindex C Streams 22787@geindex Interfacing with Sequential_IO 22788 22789This package provides subprograms that allow interfacing between 22790C streams and @cite{Sequential_IO}. The stream identifier can be 22791extracted from a file opened on the Ada side, and an Ada file 22792can be constructed from a stream opened on the C side. 22793 22794@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 22795@anchor{gnat_rm/the_gnat_library id23}@anchor{2b3}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2b4} 22796@section @cite{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 22797 22798 22799@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 22800 22801@geindex C Streams 22802@geindex Interfacing with Stream_IO 22803 22804This package provides subprograms that allow interfacing between 22805C streams and @cite{Stream_IO}. The stream identifier can be 22806extracted from a file opened on the Ada side, and an Ada file 22807can be constructed from a stream opened on the C side. 22808 22809@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 22810@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2b5}@anchor{gnat_rm/the_gnat_library id24}@anchor{2b6} 22811@section @cite{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 22812 22813 22814@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 22815 22816@geindex Unbounded_String 22817@geindex IO support 22818 22819@geindex Text_IO 22820@geindex extensions for unbounded strings 22821 22822This package provides subprograms for Text_IO for unbounded 22823strings, avoiding the necessity for an intermediate operation 22824with ordinary strings. 22825 22826@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 22827@anchor{gnat_rm/the_gnat_library id25}@anchor{2b7}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2b8} 22828@section @cite{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 22829 22830 22831@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 22832 22833@geindex Unbounded_Wide_String 22834@geindex IO support 22835 22836@geindex Text_IO 22837@geindex extensions for unbounded wide strings 22838 22839This package provides subprograms for Text_IO for unbounded 22840wide strings, avoiding the necessity for an intermediate operation 22841with ordinary wide strings. 22842 22843@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 22844@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{2b9}@anchor{gnat_rm/the_gnat_library id26}@anchor{2ba} 22845@section @cite{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 22846 22847 22848@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 22849 22850@geindex Unbounded_Wide_Wide_String 22851@geindex IO support 22852 22853@geindex Text_IO 22854@geindex extensions for unbounded wide wide strings 22855 22856This package provides subprograms for Text_IO for unbounded 22857wide wide strings, avoiding the necessity for an intermediate operation 22858with ordinary wide wide strings. 22859 22860@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 22861@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{2bb}@anchor{gnat_rm/the_gnat_library id27}@anchor{2bc} 22862@section @cite{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 22863 22864 22865@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 22866 22867@geindex C Streams 22868@geindex Interfacing with `Text_IO` 22869 22870This package provides subprograms that allow interfacing between 22871C streams and @cite{Text_IO}. The stream identifier can be 22872extracted from a file opened on the Ada side, and an Ada file 22873can be constructed from a stream opened on the C side. 22874 22875@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 22876@anchor{gnat_rm/the_gnat_library id28}@anchor{2bd}@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{2be} 22877@section @cite{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 22878 22879 22880@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 22881 22882@geindex Text_IO resetting standard files 22883 22884This procedure is used to reset the status of the standard files used 22885by Ada.Text_IO. This is useful in a situation (such as a restart in an 22886embedded application) where the status of the files may change during 22887execution (for example a standard input file may be redefined to be 22888interactive). 22889 22890@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 22891@anchor{gnat_rm/the_gnat_library id29}@anchor{2bf}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{2c0} 22892@section @cite{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 22893 22894 22895@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 22896 22897@geindex Unicode categorization 22898@geindex Wide_Character 22899 22900This package provides subprograms that allow categorization of 22901Wide_Character values according to Unicode categories. 22902 22903@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 22904@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{2c1}@anchor{gnat_rm/the_gnat_library id30}@anchor{2c2} 22905@section @cite{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 22906 22907 22908@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 22909 22910@geindex C Streams 22911@geindex Interfacing with `Wide_Text_IO` 22912 22913This package provides subprograms that allow interfacing between 22914C streams and @cite{Wide_Text_IO}. The stream identifier can be 22915extracted from a file opened on the Ada side, and an Ada file 22916can be constructed from a stream opened on the C side. 22917 22918@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 22919@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{2c3}@anchor{gnat_rm/the_gnat_library id31}@anchor{2c4} 22920@section @cite{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 22921 22922 22923@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 22924 22925@geindex Wide_Text_IO resetting standard files 22926 22927This procedure is used to reset the status of the standard files used 22928by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 22929embedded application) where the status of the files may change during 22930execution (for example a standard input file may be redefined to be 22931interactive). 22932 22933@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 22934@anchor{gnat_rm/the_gnat_library id32}@anchor{2c5}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{2c6} 22935@section @cite{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 22936 22937 22938@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 22939 22940@geindex Unicode categorization 22941@geindex Wide_Wide_Character 22942 22943This package provides subprograms that allow categorization of 22944Wide_Wide_Character values according to Unicode categories. 22945 22946@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 22947@anchor{gnat_rm/the_gnat_library id33}@anchor{2c7}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{2c8} 22948@section @cite{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 22949 22950 22951@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 22952 22953@geindex C Streams 22954@geindex Interfacing with `Wide_Wide_Text_IO` 22955 22956This package provides subprograms that allow interfacing between 22957C streams and @cite{Wide_Wide_Text_IO}. The stream identifier can be 22958extracted from a file opened on the Ada side, and an Ada file 22959can be constructed from a stream opened on the C side. 22960 22961@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 22962@anchor{gnat_rm/the_gnat_library id34}@anchor{2c9}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{2ca} 22963@section @cite{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 22964 22965 22966@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 22967 22968@geindex Wide_Wide_Text_IO resetting standard files 22969 22970This procedure is used to reset the status of the standard files used 22971by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 22972restart in an embedded application) where the status of the files may 22973change during execution (for example a standard input file may be 22974redefined to be interactive). 22975 22976@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 22977@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{2cb}@anchor{gnat_rm/the_gnat_library id35}@anchor{2cc} 22978@section @cite{GNAT.Altivec} (@code{g-altive.ads}) 22979 22980 22981@geindex GNAT.Altivec (g-altive.ads) 22982 22983@geindex AltiVec 22984 22985This is the root package of the GNAT AltiVec binding. It provides 22986definitions of constants and types common to all the versions of the 22987binding. 22988 22989@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 22990@anchor{gnat_rm/the_gnat_library id36}@anchor{2cd}@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{2ce} 22991@section @cite{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 22992 22993 22994@geindex GNAT.Altivec.Conversions (g-altcon.ads) 22995 22996@geindex AltiVec 22997 22998This package provides the Vector/View conversion routines. 22999 23000@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23001@anchor{gnat_rm/the_gnat_library id37}@anchor{2cf}@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{2d0} 23002@section @cite{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23003 23004 23005@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23006 23007@geindex AltiVec 23008 23009This package exposes the Ada interface to the AltiVec operations on 23010vector objects. A soft emulation is included by default in the GNAT 23011library. The hard binding is provided as a separate package. This unit 23012is common to both bindings. 23013 23014@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 23015@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{2d1}@anchor{gnat_rm/the_gnat_library id38}@anchor{2d2} 23016@section @cite{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23017 23018 23019@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23020 23021@geindex AltiVec 23022 23023This package exposes the various vector types part of the Ada binding 23024to AltiVec facilities. 23025 23026@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23027@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{2d3}@anchor{gnat_rm/the_gnat_library id39}@anchor{2d4} 23028@section @cite{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23029 23030 23031@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23032 23033@geindex AltiVec 23034 23035This package provides public 'View' data types from/to which private 23036vector representations can be converted via 23037GNAT.Altivec.Conversions. This allows convenient access to individual 23038vector elements and provides a simple way to initialize vector 23039objects. 23040 23041@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23042@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id40}@anchor{2d6} 23043@section @cite{GNAT.Array_Split} (@code{g-arrspl.ads}) 23044 23045 23046@geindex GNAT.Array_Split (g-arrspl.ads) 23047 23048@geindex Array splitter 23049 23050Useful array-manipulation routines: given a set of separators, split 23051an array wherever the separators appear, and provide direct access 23052to the resulting slices. 23053 23054@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 23055@anchor{gnat_rm/the_gnat_library id41}@anchor{2d7}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{2d8} 23056@section @cite{GNAT.AWK} (@code{g-awk.ads}) 23057 23058 23059@geindex GNAT.AWK (g-awk.ads) 23060 23061@geindex Parsing 23062 23063@geindex AWK 23064 23065Provides AWK-like parsing functions, with an easy interface for parsing one 23066or more files containing formatted data. The file is viewed as a database 23067where each record is a line and a field is a data element in this line. 23068 23069@node GNAT Bind_Environment g-binenv ads,GNAT Bounded_Buffers g-boubuf ads,GNAT AWK g-awk ads,The GNAT Library 23070@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{2d9}@anchor{gnat_rm/the_gnat_library id42}@anchor{2da} 23071@section @cite{GNAT.Bind_Environment} (@code{g-binenv.ads}) 23072 23073 23074@geindex GNAT.Bind_Environment (g-binenv.ads) 23075 23076@geindex Bind environment 23077 23078Provides access to key=value associations captured at bind time. 23079These associations can be specified using the @cite{-V} binder command 23080line switch. 23081 23082@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 23083@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id43}@anchor{2dc} 23084@section @cite{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 23085 23086 23087@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 23088 23089@geindex Parsing 23090 23091@geindex Bounded Buffers 23092 23093Provides a concurrent generic bounded buffer abstraction. Instances are 23094useful directly or as parts of the implementations of other abstractions, 23095such as mailboxes. 23096 23097@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 23098@anchor{gnat_rm/the_gnat_library id44}@anchor{2dd}@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{2de} 23099@section @cite{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 23100 23101 23102@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 23103 23104@geindex Parsing 23105 23106@geindex Mailboxes 23107 23108Provides a thread-safe asynchronous intertask mailbox communication facility. 23109 23110@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 23111@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id45}@anchor{2e0} 23112@section @cite{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 23113 23114 23115@geindex GNAT.Bubble_Sort (g-bubsor.ads) 23116 23117@geindex Sorting 23118 23119@geindex Bubble sort 23120 23121Provides a general implementation of bubble sort usable for sorting arbitrary 23122data items. Exchange and comparison procedures are provided by passing 23123access-to-procedure values. 23124 23125@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 23126@anchor{gnat_rm/the_gnat_library id46}@anchor{2e1}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{2e2} 23127@section @cite{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 23128 23129 23130@geindex GNAT.Bubble_Sort_A (g-busora.ads) 23131 23132@geindex Sorting 23133 23134@geindex Bubble sort 23135 23136Provides a general implementation of bubble sort usable for sorting arbitrary 23137data items. Move and comparison procedures are provided by passing 23138access-to-procedure values. This is an older version, retained for 23139compatibility. Usually @cite{GNAT.Bubble_Sort} will be preferable. 23140 23141@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 23142@anchor{gnat_rm/the_gnat_library id47}@anchor{2e3}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{2e4} 23143@section @cite{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 23144 23145 23146@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 23147 23148@geindex Sorting 23149 23150@geindex Bubble sort 23151 23152Similar to @cite{Bubble_Sort_A} except that the move and sorting procedures 23153are provided as generic parameters, this improves efficiency, especially 23154if the procedures can be inlined, at the expense of duplicating code for 23155multiple instantiations. 23156 23157@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 23158@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id48}@anchor{2e6} 23159@section @cite{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 23160 23161 23162@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 23163 23164@geindex UTF-8 representation 23165 23166@geindex Wide characte representations 23167 23168Provides a routine which given a string, reads the start of the string to 23169see whether it is one of the standard byte order marks (BOM's) which signal 23170the encoding of the string. The routine includes detection of special XML 23171sequences for various UCS input formats. 23172 23173@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 23174@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id49}@anchor{2e8} 23175@section @cite{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 23176 23177 23178@geindex GNAT.Byte_Swapping (g-bytswa.ads) 23179 23180@geindex Byte swapping 23181 23182@geindex Endianness 23183 23184General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 23185Machine-specific implementations are available in some cases. 23186 23187@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 23188@anchor{gnat_rm/the_gnat_library id50}@anchor{2e9}@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{2ea} 23189@section @cite{GNAT.Calendar} (@code{g-calend.ads}) 23190 23191 23192@geindex GNAT.Calendar (g-calend.ads) 23193 23194@geindex Calendar 23195 23196Extends the facilities provided by @cite{Ada.Calendar} to include handling 23197of days of the week, an extended @cite{Split} and @cite{Time_Of} capability. 23198Also provides conversion of @cite{Ada.Calendar.Time} values to and from the 23199C @cite{timeval} format. 23200 23201@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 23202@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id51}@anchor{2ec} 23203@section @cite{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 23204 23205 23206@geindex Calendar 23207 23208@geindex Time 23209 23210@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 23211 23212@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 23213@anchor{gnat_rm/the_gnat_library id52}@anchor{2ed}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{2ee} 23214@section @cite{GNAT.CRC32} (@code{g-crc32.ads}) 23215 23216 23217@geindex GNAT.CRC32 (g-crc32.ads) 23218 23219@geindex CRC32 23220 23221@geindex Cyclic Redundancy Check 23222 23223This package implements the CRC-32 algorithm. For a full description 23224of this algorithm see 23225@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 23226@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 23227Aug. 1988. Sarwate, D.V. 23228 23229@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 23230@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id53}@anchor{2f0} 23231@section @cite{GNAT.Case_Util} (@code{g-casuti.ads}) 23232 23233 23234@geindex GNAT.Case_Util (g-casuti.ads) 23235 23236@geindex Casing utilities 23237 23238@geindex Character handling (`GNAT.Case_Util`) 23239 23240A set of simple routines for handling upper and lower casing of strings 23241without the overhead of the full casing tables 23242in @cite{Ada.Characters.Handling}. 23243 23244@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 23245@anchor{gnat_rm/the_gnat_library id54}@anchor{2f1}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{2f2} 23246@section @cite{GNAT.CGI} (@code{g-cgi.ads}) 23247 23248 23249@geindex GNAT.CGI (g-cgi.ads) 23250 23251@geindex CGI (Common Gateway Interface) 23252 23253This is a package for interfacing a GNAT program with a Web server via the 23254Common Gateway Interface (CGI). Basically this package parses the CGI 23255parameters, which are a set of key/value pairs sent by the Web server. It 23256builds a table whose index is the key and provides some services to deal 23257with this table. 23258 23259@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 23260@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id55}@anchor{2f4} 23261@section @cite{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 23262 23263 23264@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 23265 23266@geindex CGI (Common Gateway Interface) cookie support 23267 23268@geindex Cookie support in CGI 23269 23270This is a package to interface a GNAT program with a Web server via the 23271Common Gateway Interface (CGI). It exports services to deal with Web 23272cookies (piece of information kept in the Web client software). 23273 23274@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 23275@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id56}@anchor{2f6} 23276@section @cite{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 23277 23278 23279@geindex GNAT.CGI.Debug (g-cgideb.ads) 23280 23281@geindex CGI (Common Gateway Interface) debugging 23282 23283This is a package to help debugging CGI (Common Gateway Interface) 23284programs written in Ada. 23285 23286@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 23287@anchor{gnat_rm/the_gnat_library id57}@anchor{2f7}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{2f8} 23288@section @cite{GNAT.Command_Line} (@code{g-comlin.ads}) 23289 23290 23291@geindex GNAT.Command_Line (g-comlin.ads) 23292 23293@geindex Command line 23294 23295Provides a high level interface to @cite{Ada.Command_Line} facilities, 23296including the ability to scan for named switches with optional parameters 23297and expand file names using wild card notations. 23298 23299@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 23300@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id58}@anchor{2fa} 23301@section @cite{GNAT.Compiler_Version} (@code{g-comver.ads}) 23302 23303 23304@geindex GNAT.Compiler_Version (g-comver.ads) 23305 23306@geindex Compiler Version 23307 23308@geindex Version 23309@geindex of compiler 23310 23311Provides a routine for obtaining the version of the compiler used to 23312compile the program. More accurately this is the version of the binder 23313used to bind the program (this will normally be the same as the version 23314of the compiler if a consistent tool set is used to compile all units 23315of a partition). 23316 23317@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 23318@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id59}@anchor{2fc} 23319@section @cite{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 23320 23321 23322@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 23323 23324@geindex Interrupt 23325 23326Provides a simple interface to handle Ctrl-C keyboard events. 23327 23328@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 23329@anchor{gnat_rm/the_gnat_library id60}@anchor{2fd}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{2fe} 23330@section @cite{GNAT.Current_Exception} (@code{g-curexc.ads}) 23331 23332 23333@geindex GNAT.Current_Exception (g-curexc.ads) 23334 23335@geindex Current exception 23336 23337@geindex Exception retrieval 23338 23339Provides access to information on the current exception that has been raised 23340without the need for using the Ada 95 / Ada 2005 exception choice parameter 23341specification syntax. 23342This is particularly useful in simulating typical facilities for 23343obtaining information about exceptions provided by Ada 83 compilers. 23344 23345@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 23346@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id61}@anchor{300} 23347@section @cite{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 23348 23349 23350@geindex GNAT.Debug_Pools (g-debpoo.ads) 23351 23352@geindex Debugging 23353 23354@geindex Debug pools 23355 23356@geindex Memory corruption debugging 23357 23358Provide a debugging storage pools that helps tracking memory corruption 23359problems. 23360See @cite{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}. 23361 23362@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 23363@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id62}@anchor{302} 23364@section @cite{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 23365 23366 23367@geindex GNAT.Debug_Utilities (g-debuti.ads) 23368 23369@geindex Debugging 23370 23371Provides a few useful utilities for debugging purposes, including conversion 23372to and from string images of address values. Supports both C and Ada formats 23373for hexadecimal literals. 23374 23375@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 23376@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id63}@anchor{304} 23377@section @cite{GNAT.Decode_String} (@code{g-decstr.ads}) 23378 23379 23380@geindex GNAT.Decode_String (g-decstr.ads) 23381 23382@geindex Decoding strings 23383 23384@geindex String decoding 23385 23386@geindex Wide character encoding 23387 23388@geindex UTF-8 23389 23390@geindex Unicode 23391 23392A generic package providing routines for decoding wide character and wide wide 23393character strings encoded as sequences of 8-bit characters using a specified 23394encoding method. Includes validation routines, and also routines for stepping 23395to next or previous encoded character in an encoded string. 23396Useful in conjunction with Unicode character coding. Note there is a 23397preinstantiation for UTF-8. See next entry. 23398 23399@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 23400@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id64}@anchor{306} 23401@section @cite{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 23402 23403 23404@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 23405 23406@geindex Decoding strings 23407 23408@geindex Decoding UTF-8 strings 23409 23410@geindex UTF-8 string decoding 23411 23412@geindex Wide character decoding 23413 23414@geindex UTF-8 23415 23416@geindex Unicode 23417 23418A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 23419 23420@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 23421@anchor{gnat_rm/the_gnat_library id65}@anchor{307}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{308} 23422@section @cite{GNAT.Directory_Operations} (@code{g-dirope.ads}) 23423 23424 23425@geindex GNAT.Directory_Operations (g-dirope.ads) 23426 23427@geindex Directory operations 23428 23429Provides a set of routines for manipulating directories, including changing 23430the current directory, making new directories, and scanning the files in a 23431directory. 23432 23433@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 23434@anchor{gnat_rm/the_gnat_library id66}@anchor{309}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{30a} 23435@section @cite{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 23436 23437 23438@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 23439 23440@geindex Directory operations iteration 23441 23442A child unit of GNAT.Directory_Operations providing additional operations 23443for iterating through directories. 23444 23445@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 23446@anchor{gnat_rm/the_gnat_library id67}@anchor{30b}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{30c} 23447@section @cite{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 23448 23449 23450@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 23451 23452@geindex Hash tables 23453 23454A generic implementation of hash tables that can be used to hash arbitrary 23455data. Provided in two forms, a simple form with built in hash functions, 23456and a more complex form in which the hash function is supplied. 23457 23458This package provides a facility similar to that of @cite{GNAT.HTable}, 23459except that this package declares a type that can be used to define 23460dynamic instances of the hash table, while an instantiation of 23461@cite{GNAT.HTable} creates a single instance of the hash table. 23462 23463@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 23464@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id68}@anchor{30e} 23465@section @cite{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 23466 23467 23468@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 23469 23470@geindex Table implementation 23471 23472@geindex Arrays 23473@geindex extendable 23474 23475A generic package providing a single dimension array abstraction where the 23476length of the array can be dynamically modified. 23477 23478This package provides a facility similar to that of @cite{GNAT.Table}, 23479except that this package declares a type that can be used to define 23480dynamic instances of the table, while an instantiation of 23481@cite{GNAT.Table} creates a single instance of the table type. 23482 23483@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 23484@anchor{gnat_rm/the_gnat_library id69}@anchor{30f}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{310} 23485@section @cite{GNAT.Encode_String} (@code{g-encstr.ads}) 23486 23487 23488@geindex GNAT.Encode_String (g-encstr.ads) 23489 23490@geindex Encoding strings 23491 23492@geindex String encoding 23493 23494@geindex Wide character encoding 23495 23496@geindex UTF-8 23497 23498@geindex Unicode 23499 23500A generic package providing routines for encoding wide character and wide 23501wide character strings as sequences of 8-bit characters using a specified 23502encoding method. Useful in conjunction with Unicode character coding. 23503Note there is a preinstantiation for UTF-8. See next entry. 23504 23505@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 23506@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id70}@anchor{312} 23507@section @cite{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 23508 23509 23510@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 23511 23512@geindex Encoding strings 23513 23514@geindex Encoding UTF-8 strings 23515 23516@geindex UTF-8 string encoding 23517 23518@geindex Wide character encoding 23519 23520@geindex UTF-8 23521 23522@geindex Unicode 23523 23524A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 23525 23526@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 23527@anchor{gnat_rm/the_gnat_library id71}@anchor{313}@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{314} 23528@section @cite{GNAT.Exception_Actions} (@code{g-excact.ads}) 23529 23530 23531@geindex GNAT.Exception_Actions (g-excact.ads) 23532 23533@geindex Exception actions 23534 23535Provides callbacks when an exception is raised. Callbacks can be registered 23536for specific exceptions, or when any exception is raised. This 23537can be used for instance to force a core dump to ease debugging. 23538 23539@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-expect ads,GNAT Exception_Actions g-excact ads,The GNAT Library 23540@anchor{gnat_rm/the_gnat_library id72}@anchor{315}@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{316} 23541@section @cite{GNAT.Exception_Traces} (@code{g-exctra.ads}) 23542 23543 23544@geindex GNAT.Exception_Traces (g-exctra.ads) 23545 23546@geindex Exception traces 23547 23548@geindex Debugging 23549 23550Provides an interface allowing to control automatic output upon exception 23551occurrences. 23552 23553@node GNAT Exceptions g-expect ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 23554@anchor{gnat_rm/the_gnat_library id73}@anchor{317}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-expect-ads}@anchor{318} 23555@section @cite{GNAT.Exceptions} (@code{g-expect.ads}) 23556 23557 23558@geindex GNAT.Exceptions (g-expect.ads) 23559 23560@geindex Exceptions 23561@geindex Pure 23562 23563@geindex Pure packages 23564@geindex exceptions 23565 23566Normally it is not possible to raise an exception with 23567a message from a subprogram in a pure package, since the 23568necessary types and subprograms are in @cite{Ada.Exceptions} 23569which is not a pure unit. @cite{GNAT.Exceptions} provides a 23570facility for getting around this limitation for a few 23571predefined exceptions, and for example allow raising 23572@cite{Constraint_Error} with a message from a pure subprogram. 23573 23574@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-expect ads,The GNAT Library 23575@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id74}@anchor{31a} 23576@section @cite{GNAT.Expect} (@code{g-expect.ads}) 23577 23578 23579@geindex GNAT.Expect (g-expect.ads) 23580 23581Provides a set of subprograms similar to what is available 23582with the standard Tcl Expect tool. 23583It allows you to easily spawn and communicate with an external process. 23584You can send commands or inputs to the process, and compare the output 23585with some expected regular expression. Currently @cite{GNAT.Expect} 23586is implemented on all native GNAT ports. 23587It is not implemented for cross ports, and in particular is not 23588implemented for VxWorks or LynxOS. 23589 23590@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 23591@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id75}@anchor{31c} 23592@section @cite{GNAT.Expect.TTY} (@code{g-exptty.ads}) 23593 23594 23595@geindex GNAT.Expect.TTY (g-exptty.ads) 23596 23597As GNAT.Expect but using pseudo-terminal. 23598Currently @cite{GNAT.Expect.TTY} is implemented on all native GNAT 23599ports. It is not implemented for cross ports, and 23600in particular is not implemented for VxWorks or LynxOS. 23601 23602@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 23603@anchor{gnat_rm/the_gnat_library id76}@anchor{31d}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{31e} 23604@section @cite{GNAT.Float_Control} (@code{g-flocon.ads}) 23605 23606 23607@geindex GNAT.Float_Control (g-flocon.ads) 23608 23609@geindex Floating-Point Processor 23610 23611Provides an interface for resetting the floating-point processor into the 23612mode required for correct semantic operation in Ada. Some third party 23613library calls may cause this mode to be modified, and the Reset procedure 23614in this package can be used to reestablish the required mode. 23615 23616@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 23617@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id77}@anchor{320} 23618@section @cite{GNAT.Formatted_String} (@code{g-forstr.ads}) 23619 23620 23621@geindex GNAT.Formatted_String (g-forstr.ads) 23622 23623@geindex Formatted String 23624 23625Provides support for C/C++ printf() formatted strings. The format is 23626copied from the printf() routine and should therefore gives identical 23627output. Some generic routines are provided to be able to use types 23628derived from Integer, Float or enumerations as values for the 23629formatted string. 23630 23631@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 23632@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id78}@anchor{322} 23633@section @cite{GNAT.Heap_Sort} (@code{g-heasor.ads}) 23634 23635 23636@geindex GNAT.Heap_Sort (g-heasor.ads) 23637 23638@geindex Sorting 23639 23640Provides a general implementation of heap sort usable for sorting arbitrary 23641data items. Exchange and comparison procedures are provided by passing 23642access-to-procedure values. The algorithm used is a modified heap sort 23643that performs approximately N*log(N) comparisons in the worst case. 23644 23645@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 23646@anchor{gnat_rm/the_gnat_library id79}@anchor{323}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{324} 23647@section @cite{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 23648 23649 23650@geindex GNAT.Heap_Sort_A (g-hesora.ads) 23651 23652@geindex Sorting 23653 23654Provides a general implementation of heap sort usable for sorting arbitrary 23655data items. Move and comparison procedures are provided by passing 23656access-to-procedure values. The algorithm used is a modified heap sort 23657that performs approximately N*log(N) comparisons in the worst case. 23658This differs from @cite{GNAT.Heap_Sort} in having a less convenient 23659interface, but may be slightly more efficient. 23660 23661@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 23662@anchor{gnat_rm/the_gnat_library id80}@anchor{325}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{326} 23663@section @cite{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 23664 23665 23666@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 23667 23668@geindex Sorting 23669 23670Similar to @cite{Heap_Sort_A} except that the move and sorting procedures 23671are provided as generic parameters, this improves efficiency, especially 23672if the procedures can be inlined, at the expense of duplicating code for 23673multiple instantiations. 23674 23675@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 23676@anchor{gnat_rm/the_gnat_library id81}@anchor{327}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{328} 23677@section @cite{GNAT.HTable} (@code{g-htable.ads}) 23678 23679 23680@geindex GNAT.HTable (g-htable.ads) 23681 23682@geindex Hash tables 23683 23684A generic implementation of hash tables that can be used to hash arbitrary 23685data. Provides two approaches, one a simple static approach, and the other 23686allowing arbitrary dynamic hash tables. 23687 23688@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 23689@anchor{gnat_rm/the_gnat_library id82}@anchor{329}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{32a} 23690@section @cite{GNAT.IO} (@code{g-io.ads}) 23691 23692 23693@geindex GNAT.IO (g-io.ads) 23694 23695@geindex Simple I/O 23696 23697@geindex Input/Output facilities 23698 23699A simple preelaborable input-output package that provides a subset of 23700simple Text_IO functions for reading characters and strings from 23701Standard_Input, and writing characters, strings and integers to either 23702Standard_Output or Standard_Error. 23703 23704@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 23705@anchor{gnat_rm/the_gnat_library id83}@anchor{32b}@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{32c} 23706@section @cite{GNAT.IO_Aux} (@code{g-io_aux.ads}) 23707 23708 23709@geindex GNAT.IO_Aux (g-io_aux.ads) 23710 23711@geindex Text_IO 23712 23713@geindex Input/Output facilities 23714 23715Provides some auxiliary functions for use with Text_IO, including a test 23716for whether a file exists, and functions for reading a line of text. 23717 23718@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 23719@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id84}@anchor{32e} 23720@section @cite{GNAT.Lock_Files} (@code{g-locfil.ads}) 23721 23722 23723@geindex GNAT.Lock_Files (g-locfil.ads) 23724 23725@geindex File locking 23726 23727@geindex Locking using files 23728 23729Provides a general interface for using files as locks. Can be used for 23730providing program level synchronization. 23731 23732@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 23733@anchor{gnat_rm/the_gnat_library id85}@anchor{32f}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{330} 23734@section @cite{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 23735 23736 23737@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 23738 23739@geindex Random number generation 23740 23741The original implementation of @cite{Ada.Numerics.Discrete_Random}. Uses 23742a modified version of the Blum-Blum-Shub generator. 23743 23744@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 23745@anchor{gnat_rm/the_gnat_library id86}@anchor{331}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{332} 23746@section @cite{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 23747 23748 23749@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 23750 23751@geindex Random number generation 23752 23753The original implementation of @cite{Ada.Numerics.Float_Random}. Uses 23754a modified version of the Blum-Blum-Shub generator. 23755 23756@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 23757@anchor{gnat_rm/the_gnat_library id87}@anchor{333}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{334} 23758@section @cite{GNAT.MD5} (@code{g-md5.ads}) 23759 23760 23761@geindex GNAT.MD5 (g-md5.ads) 23762 23763@geindex Message Digest MD5 23764 23765Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 23766the HMAC-MD5 message authentication function as described in RFC 2104 and 23767FIPS PUB 198. 23768 23769@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 23770@anchor{gnat_rm/the_gnat_library id88}@anchor{335}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{336} 23771@section @cite{GNAT.Memory_Dump} (@code{g-memdum.ads}) 23772 23773 23774@geindex GNAT.Memory_Dump (g-memdum.ads) 23775 23776@geindex Dump Memory 23777 23778Provides a convenient routine for dumping raw memory to either the 23779standard output or standard error files. Uses GNAT.IO for actual 23780output. 23781 23782@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 23783@anchor{gnat_rm/the_gnat_library id89}@anchor{337}@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{338} 23784@section @cite{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 23785 23786 23787@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 23788 23789@geindex Exception 23790@geindex obtaining most recent 23791 23792Provides access to the most recently raised exception. Can be used for 23793various logging purposes, including duplicating functionality of some 23794Ada 83 implementation dependent extensions. 23795 23796@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 23797@anchor{gnat_rm/the_gnat_library id90}@anchor{339}@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{33a} 23798@section @cite{GNAT.OS_Lib} (@code{g-os_lib.ads}) 23799 23800 23801@geindex GNAT.OS_Lib (g-os_lib.ads) 23802 23803@geindex Operating System interface 23804 23805@geindex Spawn capability 23806 23807Provides a range of target independent operating system interface functions, 23808including time/date management, file operations, subprocess management, 23809including a portable spawn procedure, and access to environment variables 23810and error return codes. 23811 23812@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 23813@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id91}@anchor{33c} 23814@section @cite{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 23815 23816 23817@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 23818 23819@geindex Hash functions 23820 23821Provides a generator of static minimal perfect hash functions. No 23822collisions occur and each item can be retrieved from the table in one 23823probe (perfect property). The hash table size corresponds to the exact 23824size of the key set and no larger (minimal property). The key set has to 23825be know in advance (static property). The hash functions are also order 23826preserving. If w2 is inserted after w1 in the generator, their 23827hashcode are in the same order. These hashing functions are very 23828convenient for use with realtime applications. 23829 23830@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 23831@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id92}@anchor{33e} 23832@section @cite{GNAT.Random_Numbers} (@code{g-rannum.ads}) 23833 23834 23835@geindex GNAT.Random_Numbers (g-rannum.ads) 23836 23837@geindex Random number generation 23838 23839Provides random number capabilities which extend those available in the 23840standard Ada library and are more convenient to use. 23841 23842@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 23843@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{210}@anchor{gnat_rm/the_gnat_library id93}@anchor{33f} 23844@section @cite{GNAT.Regexp} (@code{g-regexp.ads}) 23845 23846 23847@geindex GNAT.Regexp (g-regexp.ads) 23848 23849@geindex Regular expressions 23850 23851@geindex Pattern matching 23852 23853A simple implementation of regular expressions, using a subset of regular 23854expression syntax copied from familiar Unix style utilities. This is the 23855simplest of the three pattern matching packages provided, and is particularly 23856suitable for 'file globbing' applications. 23857 23858@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 23859@anchor{gnat_rm/the_gnat_library id94}@anchor{340}@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{341} 23860@section @cite{GNAT.Registry} (@code{g-regist.ads}) 23861 23862 23863@geindex GNAT.Registry (g-regist.ads) 23864 23865@geindex Windows Registry 23866 23867This is a high level binding to the Windows registry. It is possible to 23868do simple things like reading a key value, creating a new key. For full 23869registry API, but at a lower level of abstraction, refer to the Win32.Winreg 23870package provided with the Win32Ada binding 23871 23872@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 23873@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{342}@anchor{gnat_rm/the_gnat_library id95}@anchor{343} 23874@section @cite{GNAT.Regpat} (@code{g-regpat.ads}) 23875 23876 23877@geindex GNAT.Regpat (g-regpat.ads) 23878 23879@geindex Regular expressions 23880 23881@geindex Pattern matching 23882 23883A complete implementation of Unix-style regular expression matching, copied 23884from the original V7 style regular expression library written in C by 23885Henry Spencer (and binary compatible with this C library). 23886 23887@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 23888@anchor{gnat_rm/the_gnat_library id96}@anchor{344}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{345} 23889@section @cite{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 23890 23891 23892@geindex GNAT.Rewrite_Data (g-rewdat.ads) 23893 23894@geindex Rewrite data 23895 23896A unit to rewrite on-the-fly string occurrences in a stream of 23897data. The implementation has a very minimal memory footprint as the 23898full content to be processed is not loaded into memory all at once. This makes 23899this interface usable for large files or socket streams. 23900 23901@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 23902@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{346}@anchor{gnat_rm/the_gnat_library id97}@anchor{347} 23903@section @cite{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 23904 23905 23906@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 23907 23908@geindex Secondary Stack Info 23909 23910Provide the capability to query the high water mark of the current task's 23911secondary stack. 23912 23913@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 23914@anchor{gnat_rm/the_gnat_library id98}@anchor{348}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{349} 23915@section @cite{GNAT.Semaphores} (@code{g-semaph.ads}) 23916 23917 23918@geindex GNAT.Semaphores (g-semaph.ads) 23919 23920@geindex Semaphores 23921 23922Provides classic counting and binary semaphores using protected types. 23923 23924@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 23925@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{34a}@anchor{gnat_rm/the_gnat_library id99}@anchor{34b} 23926@section @cite{GNAT.Serial_Communications} (@code{g-sercom.ads}) 23927 23928 23929@geindex GNAT.Serial_Communications (g-sercom.ads) 23930 23931@geindex Serial_Communications 23932 23933Provides a simple interface to send and receive data over a serial 23934port. This is only supported on GNU/Linux and Windows. 23935 23936@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 23937@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id100}@anchor{34d} 23938@section @cite{GNAT.SHA1} (@code{g-sha1.ads}) 23939 23940 23941@geindex GNAT.SHA1 (g-sha1.ads) 23942 23943@geindex Secure Hash Algorithm SHA-1 23944 23945Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 23946and RFC 3174, and the HMAC-SHA1 message authentication function as described 23947in RFC 2104 and FIPS PUB 198. 23948 23949@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 23950@anchor{gnat_rm/the_gnat_library id101}@anchor{34e}@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{34f} 23951@section @cite{GNAT.SHA224} (@code{g-sha224.ads}) 23952 23953 23954@geindex GNAT.SHA224 (g-sha224.ads) 23955 23956@geindex Secure Hash Algorithm SHA-224 23957 23958Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 23959and the HMAC-SHA224 message authentication function as described 23960in RFC 2104 and FIPS PUB 198. 23961 23962@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 23963@anchor{gnat_rm/the_gnat_library id102}@anchor{350}@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{351} 23964@section @cite{GNAT.SHA256} (@code{g-sha256.ads}) 23965 23966 23967@geindex GNAT.SHA256 (g-sha256.ads) 23968 23969@geindex Secure Hash Algorithm SHA-256 23970 23971Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 23972and the HMAC-SHA256 message authentication function as described 23973in RFC 2104 and FIPS PUB 198. 23974 23975@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 23976@anchor{gnat_rm/the_gnat_library id103}@anchor{352}@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{353} 23977@section @cite{GNAT.SHA384} (@code{g-sha384.ads}) 23978 23979 23980@geindex GNAT.SHA384 (g-sha384.ads) 23981 23982@geindex Secure Hash Algorithm SHA-384 23983 23984Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 23985and the HMAC-SHA384 message authentication function as described 23986in RFC 2104 and FIPS PUB 198. 23987 23988@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 23989@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{354}@anchor{gnat_rm/the_gnat_library id104}@anchor{355} 23990@section @cite{GNAT.SHA512} (@code{g-sha512.ads}) 23991 23992 23993@geindex GNAT.SHA512 (g-sha512.ads) 23994 23995@geindex Secure Hash Algorithm SHA-512 23996 23997Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 23998and the HMAC-SHA512 message authentication function as described 23999in RFC 2104 and FIPS PUB 198. 24000 24001@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24002@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{356}@anchor{gnat_rm/the_gnat_library id105}@anchor{357} 24003@section @cite{GNAT.Signals} (@code{g-signal.ads}) 24004 24005 24006@geindex GNAT.Signals (g-signal.ads) 24007 24008@geindex Signals 24009 24010Provides the ability to manipulate the blocked status of signals on supported 24011targets. 24012 24013@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24014@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{358}@anchor{gnat_rm/the_gnat_library id106}@anchor{359} 24015@section @cite{GNAT.Sockets} (@code{g-socket.ads}) 24016 24017 24018@geindex GNAT.Sockets (g-socket.ads) 24019 24020@geindex Sockets 24021 24022A high level and portable interface to develop sockets based applications. 24023This package is based on the sockets thin binding found in 24024@cite{GNAT.Sockets.Thin}. Currently @cite{GNAT.Sockets} is implemented 24025on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24026the LynxOS cross port. 24027 24028@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24029@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{35a}@anchor{gnat_rm/the_gnat_library id107}@anchor{35b} 24030@section @cite{GNAT.Source_Info} (@code{g-souinf.ads}) 24031 24032 24033@geindex GNAT.Source_Info (g-souinf.ads) 24034 24035@geindex Source Information 24036 24037Provides subprograms that give access to source code information known at 24038compile time, such as the current file name and line number. Also provides 24039subprograms yielding the date and time of the current compilation (like the 24040C macros @cite{__DATE__} and @cite{__TIME__}) 24041 24042@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 24043@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{35c}@anchor{gnat_rm/the_gnat_library id108}@anchor{35d} 24044@section @cite{GNAT.Spelling_Checker} (@code{g-speche.ads}) 24045 24046 24047@geindex GNAT.Spelling_Checker (g-speche.ads) 24048 24049@geindex Spell checking 24050 24051Provides a function for determining whether one string is a plausible 24052near misspelling of another string. 24053 24054@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 24055@anchor{gnat_rm/the_gnat_library id109}@anchor{35e}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{35f} 24056@section @cite{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 24057 24058 24059@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 24060 24061@geindex Spell checking 24062 24063Provides a generic function that can be instantiated with a string type for 24064determining whether one string is a plausible near misspelling of another 24065string. 24066 24067@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 24068@anchor{gnat_rm/the_gnat_library id110}@anchor{360}@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{361} 24069@section @cite{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 24070 24071 24072@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 24073 24074@geindex SPITBOL pattern matching 24075 24076@geindex Pattern matching 24077 24078A complete implementation of SNOBOL4 style pattern matching. This is the 24079most elaborate of the pattern matching packages provided. It fully duplicates 24080the SNOBOL4 dynamic pattern construction and matching capabilities, using the 24081efficient algorithm developed by Robert Dewar for the SPITBOL system. 24082 24083@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 24084@anchor{gnat_rm/the_gnat_library id111}@anchor{362}@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{363} 24085@section @cite{GNAT.Spitbol} (@code{g-spitbo.ads}) 24086 24087 24088@geindex GNAT.Spitbol (g-spitbo.ads) 24089 24090@geindex SPITBOL interface 24091 24092The top level package of the collection of SPITBOL-style functionality, this 24093package provides basic SNOBOL4 string manipulation functions, such as 24094Pad, Reverse, Trim, Substr capability, as well as a generic table function 24095useful for constructing arbitrary mappings from strings in the style of 24096the SNOBOL4 TABLE function. 24097 24098@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 24099@anchor{gnat_rm/the_gnat_library id112}@anchor{364}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{365} 24100@section @cite{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 24101 24102 24103@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 24104 24105@geindex Sets of strings 24106 24107@geindex SPITBOL Tables 24108 24109A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table} 24110for type @cite{Standard.Boolean}, giving an implementation of sets of 24111string values. 24112 24113@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 24114@anchor{gnat_rm/the_gnat_library id113}@anchor{366}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{367} 24115@section @cite{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 24116 24117 24118@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 24119 24120@geindex Integer maps 24121 24122@geindex Maps 24123 24124@geindex SPITBOL Tables 24125 24126A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table} 24127for type @cite{Standard.Integer}, giving an implementation of maps 24128from string to integer values. 24129 24130@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 24131@anchor{gnat_rm/the_gnat_library id114}@anchor{368}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{369} 24132@section @cite{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 24133 24134 24135@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 24136 24137@geindex String maps 24138 24139@geindex Maps 24140 24141@geindex SPITBOL Tables 24142 24143A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table} for 24144a variable length string type, giving an implementation of general 24145maps from strings to strings. 24146 24147@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 24148@anchor{gnat_rm/the_gnat_library id115}@anchor{36a}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{36b} 24149@section @cite{GNAT.SSE} (@code{g-sse.ads}) 24150 24151 24152@geindex GNAT.SSE (g-sse.ads) 24153 24154Root of a set of units aimed at offering Ada bindings to a subset of 24155the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 24156targets. It exposes vector component types together with a general 24157introduction to the binding contents and use. 24158 24159@node GNAT SSE Vector_Types g-ssvety ads,GNAT Strings g-string ads,GNAT SSE g-sse ads,The GNAT Library 24160@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{36c}@anchor{gnat_rm/the_gnat_library id116}@anchor{36d} 24161@section @cite{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 24162 24163 24164@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 24165 24166SSE vector types for use with SSE related intrinsics. 24167 24168@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 24169@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{36e}@anchor{gnat_rm/the_gnat_library id117}@anchor{36f} 24170@section @cite{GNAT.Strings} (@code{g-string.ads}) 24171 24172 24173@geindex GNAT.Strings (g-string.ads) 24174 24175Common String access types and related subprograms. Basically it 24176defines a string access and an array of string access types. 24177 24178@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 24179@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{370}@anchor{gnat_rm/the_gnat_library id118}@anchor{371} 24180@section @cite{GNAT.String_Split} (@code{g-strspl.ads}) 24181 24182 24183@geindex GNAT.String_Split (g-strspl.ads) 24184 24185@geindex String splitter 24186 24187Useful string manipulation routines: given a set of separators, split 24188a string wherever the separators appear, and provide direct access 24189to the resulting slices. This package is instantiated from 24190@cite{GNAT.Array_Split}. 24191 24192@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 24193@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{372}@anchor{gnat_rm/the_gnat_library id119}@anchor{373} 24194@section @cite{GNAT.Table} (@code{g-table.ads}) 24195 24196 24197@geindex GNAT.Table (g-table.ads) 24198 24199@geindex Table implementation 24200 24201@geindex Arrays 24202@geindex extendable 24203 24204A generic package providing a single dimension array abstraction where the 24205length of the array can be dynamically modified. 24206 24207This package provides a facility similar to that of @cite{GNAT.Dynamic_Tables}, 24208except that this package declares a single instance of the table type, 24209while an instantiation of @cite{GNAT.Dynamic_Tables} creates a type that can be 24210used to define dynamic instances of the table. 24211 24212@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 24213@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{374}@anchor{gnat_rm/the_gnat_library id120}@anchor{375} 24214@section @cite{GNAT.Task_Lock} (@code{g-tasloc.ads}) 24215 24216 24217@geindex GNAT.Task_Lock (g-tasloc.ads) 24218 24219@geindex Task synchronization 24220 24221@geindex Task locking 24222 24223@geindex Locking 24224 24225A very simple facility for locking and unlocking sections of code using a 24226single global task lock. Appropriate for use in situations where contention 24227between tasks is very rarely expected. 24228 24229@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 24230@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{376}@anchor{gnat_rm/the_gnat_library id121}@anchor{377} 24231@section @cite{GNAT.Time_Stamp} (@code{g-timsta.ads}) 24232 24233 24234@geindex GNAT.Time_Stamp (g-timsta.ads) 24235 24236@geindex Time stamp 24237 24238@geindex Current time 24239 24240Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 24241represents the current date and time in ISO 8601 format. This is a very simple 24242routine with minimal code and there are no dependencies on any other unit. 24243 24244@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 24245@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{378}@anchor{gnat_rm/the_gnat_library id122}@anchor{379} 24246@section @cite{GNAT.Threads} (@code{g-thread.ads}) 24247 24248 24249@geindex GNAT.Threads (g-thread.ads) 24250 24251@geindex Foreign threads 24252 24253@geindex Threads 24254@geindex foreign 24255 24256Provides facilities for dealing with foreign threads which need to be known 24257by the GNAT run-time system. Consult the documentation of this package for 24258further details if your program has threads that are created by a non-Ada 24259environment which then accesses Ada code. 24260 24261@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 24262@anchor{gnat_rm/the_gnat_library id123}@anchor{37a}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{37b} 24263@section @cite{GNAT.Traceback} (@code{g-traceb.ads}) 24264 24265 24266@geindex GNAT.Traceback (g-traceb.ads) 24267 24268@geindex Trace back facilities 24269 24270Provides a facility for obtaining non-symbolic traceback information, useful 24271in various debugging situations. 24272 24273@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 24274@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{37c}@anchor{gnat_rm/the_gnat_library id124}@anchor{37d} 24275@section @cite{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 24276 24277 24278@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 24279 24280@geindex Trace back facilities 24281 24282@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 24283@anchor{gnat_rm/the_gnat_library id125}@anchor{37e}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{37f} 24284@section @cite{GNAT.UTF_32} (@code{g-table.ads}) 24285 24286 24287@geindex GNAT.UTF_32 (g-table.ads) 24288 24289@geindex Wide character codes 24290 24291This is a package intended to be used in conjunction with the 24292@cite{Wide_Character} type in Ada 95 and the 24293@cite{Wide_Wide_Character} type in Ada 2005 (available 24294in @cite{GNAT} in Ada 2005 mode). This package contains 24295Unicode categorization routines, as well as lexical 24296categorization routines corresponding to the Ada 2005 24297lexical rules for identifiers and strings, and also a 24298lower case to upper case fold routine corresponding to 24299the Ada 2005 rules for identifier equivalence. 24300 24301@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 24302@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{380}@anchor{gnat_rm/the_gnat_library id126}@anchor{381} 24303@section @cite{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 24304 24305 24306@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 24307 24308@geindex Spell checking 24309 24310Provides a function for determining whether one wide wide string is a plausible 24311near misspelling of another wide wide string, where the strings are represented 24312using the UTF_32_String type defined in System.Wch_Cnv. 24313 24314@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 24315@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{382}@anchor{gnat_rm/the_gnat_library id127}@anchor{383} 24316@section @cite{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 24317 24318 24319@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 24320 24321@geindex Spell checking 24322 24323Provides a function for determining whether one wide string is a plausible 24324near misspelling of another wide string. 24325 24326@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 24327@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{384}@anchor{gnat_rm/the_gnat_library id128}@anchor{385} 24328@section @cite{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 24329 24330 24331@geindex GNAT.Wide_String_Split (g-wistsp.ads) 24332 24333@geindex Wide_String splitter 24334 24335Useful wide string manipulation routines: given a set of separators, split 24336a wide string wherever the separators appear, and provide direct access 24337to the resulting slices. This package is instantiated from 24338@cite{GNAT.Array_Split}. 24339 24340@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 24341@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id129}@anchor{387} 24342@section @cite{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 24343 24344 24345@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 24346 24347@geindex Spell checking 24348 24349Provides a function for determining whether one wide wide string is a plausible 24350near misspelling of another wide wide string. 24351 24352@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 24353@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id130}@anchor{389} 24354@section @cite{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 24355 24356 24357@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 24358 24359@geindex Wide_Wide_String splitter 24360 24361Useful wide wide string manipulation routines: given a set of separators, split 24362a wide wide string wherever the separators appear, and provide direct access 24363to the resulting slices. This package is instantiated from 24364@cite{GNAT.Array_Split}. 24365 24366@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 24367@anchor{gnat_rm/the_gnat_library id131}@anchor{38a}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{38b} 24368@section @cite{Interfaces.C.Extensions} (@code{i-cexten.ads}) 24369 24370 24371@geindex Interfaces.C.Extensions (i-cexten.ads) 24372 24373This package contains additional C-related definitions, intended 24374for use with either manually or automatically generated bindings 24375to C libraries. 24376 24377@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 24378@anchor{gnat_rm/the_gnat_library id132}@anchor{38c}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{38d} 24379@section @cite{Interfaces.C.Streams} (@code{i-cstrea.ads}) 24380 24381 24382@geindex Interfaces.C.Streams (i-cstrea.ads) 24383 24384@geindex C streams 24385@geindex interfacing 24386 24387This package is a binding for the most commonly used operations 24388on C streams. 24389 24390@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 24391@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id133}@anchor{38f} 24392@section @cite{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 24393 24394 24395@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 24396 24397@geindex IBM Packed Format 24398 24399@geindex Packed Decimal 24400 24401This package provides a set of routines for conversions to and 24402from a packed decimal format compatible with that used on IBM 24403mainframes. 24404 24405@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 24406@anchor{gnat_rm/the_gnat_library id134}@anchor{390}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{391} 24407@section @cite{Interfaces.VxWorks} (@code{i-vxwork.ads}) 24408 24409 24410@geindex Interfaces.VxWorks (i-vxwork.ads) 24411 24412@geindex Interfacing to VxWorks 24413 24414@geindex VxWorks 24415@geindex interfacing 24416 24417This package provides a limited binding to the VxWorks API. 24418In particular, it interfaces with the 24419VxWorks hardware interrupt facilities. 24420 24421@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 24422@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id135}@anchor{393} 24423@section @cite{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 24424 24425 24426@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 24427 24428@geindex Interfacing to VxWorks' I/O 24429 24430@geindex VxWorks 24431@geindex I/O interfacing 24432 24433@geindex VxWorks 24434@geindex Get_Immediate 24435 24436@geindex Get_Immediate 24437@geindex VxWorks 24438 24439This package provides a binding to the ioctl (IO/Control) 24440function of VxWorks, defining a set of option values and 24441function codes. A particular use of this package is 24442to enable the use of Get_Immediate under VxWorks. 24443 24444@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 24445@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id136}@anchor{395} 24446@section @cite{System.Address_Image} (@code{s-addima.ads}) 24447 24448 24449@geindex System.Address_Image (s-addima.ads) 24450 24451@geindex Address image 24452 24453@geindex Image 24454@geindex of an address 24455 24456This function provides a useful debugging 24457function that gives an (implementation dependent) 24458string which identifies an address. 24459 24460@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 24461@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id137}@anchor{397} 24462@section @cite{System.Assertions} (@code{s-assert.ads}) 24463 24464 24465@geindex System.Assertions (s-assert.ads) 24466 24467@geindex Assertions 24468 24469@geindex Assert_Failure 24470@geindex exception 24471 24472This package provides the declaration of the exception raised 24473by an run-time assertion failure, as well as the routine that 24474is used internally to raise this assertion. 24475 24476@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 24477@anchor{gnat_rm/the_gnat_library id138}@anchor{398}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{399} 24478@section @cite{System.Atomic_Counters} (@code{s-atocou.ads}) 24479 24480 24481@geindex System.Atomic_Counters (s-atocou.ads) 24482 24483This package provides the declaration of an atomic counter type, 24484together with efficient routines (using hardware 24485synchronization primitives) for incrementing, decrementing, 24486and testing of these counters. This package is implemented 24487on most targets, including all Alpha, ia64, PowerPC, SPARC V9, 24488x86, and x86_64 platforms. 24489 24490@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 24491@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id139}@anchor{39b} 24492@section @cite{System.Memory} (@code{s-memory.ads}) 24493 24494 24495@geindex System.Memory (s-memory.ads) 24496 24497@geindex Memory allocation 24498 24499This package provides the interface to the low level routines used 24500by the generated code for allocation and freeing storage for the 24501default storage pool (analogous to the C routines malloc and free. 24502It also provides a reallocation interface analogous to the C routine 24503realloc. The body of this unit may be modified to provide alternative 24504allocation mechanisms for the default pool, and in addition, direct 24505calls to this unit may be made for low level allocation uses (for 24506example see the body of @cite{GNAT.Tables}). 24507 24508@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 24509@anchor{gnat_rm/the_gnat_library id140}@anchor{39c}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{39d} 24510@section @cite{System.Multiprocessors} (@code{s-multip.ads}) 24511 24512 24513@geindex System.Multiprocessors (s-multip.ads) 24514 24515@geindex Multiprocessor interface 24516 24517This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 24518in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 24519technically an implementation-defined addition). 24520 24521@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 24522@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id141}@anchor{39f} 24523@section @cite{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 24524 24525 24526@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 24527 24528@geindex Multiprocessor interface 24529 24530This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 24531in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 24532technically an implementation-defined addition). 24533 24534@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 24535@anchor{gnat_rm/the_gnat_library id142}@anchor{3a0}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3a1} 24536@section @cite{System.Partition_Interface} (@code{s-parint.ads}) 24537 24538 24539@geindex System.Partition_Interface (s-parint.ads) 24540 24541@geindex Partition interfacing functions 24542 24543This package provides facilities for partition interfacing. It 24544is used primarily in a distribution context when using Annex E 24545with @cite{GLADE}. 24546 24547@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 24548@anchor{gnat_rm/the_gnat_library id143}@anchor{3a2}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3a3} 24549@section @cite{System.Pool_Global} (@code{s-pooglo.ads}) 24550 24551 24552@geindex System.Pool_Global (s-pooglo.ads) 24553 24554@geindex Storage pool 24555@geindex global 24556 24557@geindex Global storage pool 24558 24559This package provides a storage pool that is equivalent to the default 24560storage pool used for access types for which no pool is specifically 24561declared. It uses malloc/free to allocate/free and does not attempt to 24562do any automatic reclamation. 24563 24564@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 24565@anchor{gnat_rm/the_gnat_library id144}@anchor{3a4}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3a5} 24566@section @cite{System.Pool_Local} (@code{s-pooloc.ads}) 24567 24568 24569@geindex System.Pool_Local (s-pooloc.ads) 24570 24571@geindex Storage pool 24572@geindex local 24573 24574@geindex Local storage pool 24575 24576This package provides a storage pool that is intended for use with locally 24577defined access types. It uses malloc/free for allocate/free, and maintains 24578a list of allocated blocks, so that all storage allocated for the pool can 24579be freed automatically when the pool is finalized. 24580 24581@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 24582@anchor{gnat_rm/the_gnat_library id145}@anchor{3a6}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3a7} 24583@section @cite{System.Restrictions} (@code{s-restri.ads}) 24584 24585 24586@geindex System.Restrictions (s-restri.ads) 24587 24588@geindex Run-time restrictions access 24589 24590This package provides facilities for accessing at run time 24591the status of restrictions specified at compile time for 24592the partition. Information is available both with regard 24593to actual restrictions specified, and with regard to 24594compiler determined information on which restrictions 24595are violated by one or more packages in the partition. 24596 24597@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 24598@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id146}@anchor{3a9} 24599@section @cite{System.Rident} (@code{s-rident.ads}) 24600 24601 24602@geindex System.Rident (s-rident.ads) 24603 24604@geindex Restrictions definitions 24605 24606This package provides definitions of the restrictions 24607identifiers supported by GNAT, and also the format of 24608the restrictions provided in package System.Restrictions. 24609It is not normally necessary to @cite{with} this generic package 24610since the necessary instantiation is included in 24611package System.Restrictions. 24612 24613@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 24614@anchor{gnat_rm/the_gnat_library id147}@anchor{3aa}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3ab} 24615@section @cite{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 24616 24617 24618@geindex System.Strings.Stream_Ops (s-ststop.ads) 24619 24620@geindex Stream operations 24621 24622@geindex String stream operations 24623 24624This package provides a set of stream subprograms for standard string types. 24625It is intended primarily to support implicit use of such subprograms when 24626stream attributes are applied to string types, but the subprograms in this 24627package can be used directly by application programs. 24628 24629@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 24630@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id148}@anchor{3ad} 24631@section @cite{System.Unsigned_Types} (@code{s-unstyp.ads}) 24632 24633 24634@geindex System.Unsigned_Types (s-unstyp.ads) 24635 24636This package contains definitions of standard unsigned types that 24637correspond in size to the standard signed types declared in Standard, 24638and (unlike the types in Interfaces) have corresponding names. It 24639also contains some related definitions for other specialized types 24640used by the compiler in connection with packed array types. 24641 24642@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 24643@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id149}@anchor{3af} 24644@section @cite{System.Wch_Cnv} (@code{s-wchcnv.ads}) 24645 24646 24647@geindex System.Wch_Cnv (s-wchcnv.ads) 24648 24649@geindex Wide Character 24650@geindex Representation 24651 24652@geindex Wide String 24653@geindex Conversion 24654 24655@geindex Representation of wide characters 24656 24657This package provides routines for converting between 24658wide and wide wide characters and a representation as a value of type 24659@cite{Standard.String}, using a specified wide character 24660encoding method. It uses definitions in 24661package @cite{System.Wch_Con}. 24662 24663@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 24664@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id150}@anchor{3b1} 24665@section @cite{System.Wch_Con} (@code{s-wchcon.ads}) 24666 24667 24668@geindex System.Wch_Con (s-wchcon.ads) 24669 24670This package provides definitions and descriptions of 24671the various methods used for encoding wide characters 24672in ordinary strings. These definitions are used by 24673the package @cite{System.Wch_Cnv}. 24674 24675@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 24676@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3b2}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3b3} 24677@chapter Interfacing to Other Languages 24678 24679 24680The facilities in Annex B of the Ada Reference Manual are fully 24681implemented in GNAT, and in addition, a full interface to C++ is 24682provided. 24683 24684@menu 24685* Interfacing to C:: 24686* Interfacing to C++:: 24687* Interfacing to COBOL:: 24688* Interfacing to Fortran:: 24689* Interfacing to non-GNAT Ada code:: 24690 24691@end menu 24692 24693@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 24694@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{3b4}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{3b5} 24695@section Interfacing to C 24696 24697 24698Interfacing to C with GNAT can use one of two approaches: 24699 24700 24701@itemize * 24702 24703@item 24704The types in the package @cite{Interfaces.C} may be used. 24705 24706@item 24707Standard Ada types may be used directly. This may be less portable to 24708other compilers, but will work on all GNAT compilers, which guarantee 24709correspondence between the C and Ada types. 24710@end itemize 24711 24712Pragma @cite{Convention C} may be applied to Ada types, but mostly has no 24713effect, since this is the default. The following table shows the 24714correspondence between Ada scalar types and the corresponding C types. 24715 24716 24717@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 24718@headitem 24719 24720Ada Type 24721 24722@tab 24723 24724C Type 24725 24726@item 24727 24728@code{Integer} 24729 24730@tab 24731 24732@code{int} 24733 24734@item 24735 24736@code{Short_Integer} 24737 24738@tab 24739 24740@code{short} 24741 24742@item 24743 24744@code{Short_Short_Integer} 24745 24746@tab 24747 24748@code{signed char} 24749 24750@item 24751 24752@code{Long_Integer} 24753 24754@tab 24755 24756@code{long} 24757 24758@item 24759 24760@code{Long_Long_Integer} 24761 24762@tab 24763 24764@code{long long} 24765 24766@item 24767 24768@code{Short_Float} 24769 24770@tab 24771 24772@code{float} 24773 24774@item 24775 24776@code{Float} 24777 24778@tab 24779 24780@code{float} 24781 24782@item 24783 24784@code{Long_Float} 24785 24786@tab 24787 24788@code{double} 24789 24790@item 24791 24792@code{Long_Long_Float} 24793 24794@tab 24795 24796This is the longest floating-point type supported by the hardware. 24797 24798@end multitable 24799 24800 24801Additionally, there are the following general correspondences between Ada 24802and C types: 24803 24804 24805@itemize * 24806 24807@item 24808Ada enumeration types map to C enumeration types directly if pragma 24809@cite{Convention C} is specified, which causes them to have int 24810length. Without pragma @cite{Convention C}, Ada enumeration types map to 248118, 16, or 32 bits (i.e., C types @cite{signed char}, @cite{short}, 24812@cite{int}, respectively) depending on the number of values passed. 24813This is the only case in which pragma @cite{Convention C} affects the 24814representation of an Ada type. 24815 24816@item 24817Ada access types map to C pointers, except for the case of pointers to 24818unconstrained types in Ada, which have no direct C equivalent. 24819 24820@item 24821Ada arrays map directly to C arrays. 24822 24823@item 24824Ada records map directly to C structures. 24825 24826@item 24827Packed Ada records map to C structures where all members are bit fields 24828of the length corresponding to the @code{type'Size} value in Ada. 24829@end itemize 24830 24831@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 24832@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{3b6}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{3f} 24833@section Interfacing to C++ 24834 24835 24836The interface to C++ makes use of the following pragmas, which are 24837primarily intended to be constructed automatically using a binding generator 24838tool, although it is possible to construct them by hand. 24839 24840Using these pragmas it is possible to achieve complete 24841inter-operability between Ada tagged types and C++ class definitions. 24842See @ref{7,,Implementation Defined Pragmas}, for more details. 24843 24844 24845@table @asis 24846 24847@item @emph{pragma CPP_Class ([Entity =>] `LOCAL_NAME`)} 24848 24849The argument denotes an entity in the current declarative region that is 24850declared as a tagged or untagged record type. It indicates that the type 24851corresponds to an externally declared C++ class type, and is to be laid 24852out the same way that C++ would lay out the type. 24853 24854Note: Pragma @cite{CPP_Class} is currently obsolete. It is supported 24855for backward compatibility but its functionality is available 24856using pragma @cite{Import} with @cite{Convention} = @cite{CPP}. 24857 24858@item @emph{pragma CPP_Constructor ([Entity =>] `LOCAL_NAME`)} 24859 24860This pragma identifies an imported function (imported in the usual way 24861with pragma @cite{Import}) as corresponding to a C++ constructor. 24862@end table 24863 24864A few restrictions are placed on the use of the @cite{Access} attribute 24865in conjunction with subprograms subject to convention @cite{CPP}: the 24866attribute may be used neither on primitive operations of a tagged 24867record type with convention @cite{CPP}, imported or not, nor on 24868subprograms imported with pragma @cite{CPP_Constructor}. 24869 24870In addition, C++ exceptions are propagated and can be handled in an 24871@cite{others} choice of an exception handler. The corresponding Ada 24872occurrence has no message, and the simple name of the exception identity 24873contains @code{Foreign_Exception}. Finalization and awaiting dependent 24874tasks works properly when such foreign exceptions are propagated. 24875 24876It is also possible to import a C++ exception using the following syntax: 24877 24878@example 24879LOCAL_NAME : exception; 24880pragma Import (Cpp, 24881 [Entity =>] LOCAL_NAME, 24882 [External_Name =>] static_string_EXPRESSION); 24883@end example 24884 24885The @cite{External_Name} is the name of the C++ RTTI symbol. You can then 24886cover a specific C++ exception in an exception handler. 24887 24888@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 24889@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{3b7}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{3b8} 24890@section Interfacing to COBOL 24891 24892 24893Interfacing to COBOL is achieved as described in section B.4 of 24894the Ada Reference Manual. 24895 24896@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 24897@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{3b9}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{3ba} 24898@section Interfacing to Fortran 24899 24900 24901Interfacing to Fortran is achieved as described in section B.5 of the 24902Ada Reference Manual. The pragma @cite{Convention Fortran}, applied to a 24903multi-dimensional array causes the array to be stored in column-major 24904order as required for convenient interface to Fortran. 24905 24906@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 24907@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{3bb}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{3bc} 24908@section Interfacing to non-GNAT Ada code 24909 24910 24911It is possible to specify the convention @cite{Ada} in a pragma 24912@cite{Import} or pragma @cite{Export}. However this refers to 24913the calling conventions used by GNAT, which may or may not be 24914similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 24915compiler to allow interoperation. 24916 24917If arguments types are kept simple, and if the foreign compiler generally 24918follows system calling conventions, then it may be possible to integrate 24919files compiled by other Ada compilers, provided that the elaboration 24920issues are adequately addressed (for example by eliminating the 24921need for any load time elaboration). 24922 24923In particular, GNAT running on VMS is designed to 24924be highly compatible with the DEC Ada 83 compiler, so this is one 24925case in which it is possible to import foreign units of this type, 24926provided that the data items passed are restricted to simple scalar 24927values or simple record types without variants, or simple array 24928types with fixed bounds. 24929 24930@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 24931@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{3bd}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{3be} 24932@chapter Specialized Needs Annexes 24933 24934 24935Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 24936required in all implementations. However, as described in this chapter, 24937GNAT implements all of these annexes: 24938 24939 24940@table @asis 24941 24942@item @emph{Systems Programming (Annex C)} 24943 24944The Systems Programming Annex is fully implemented. 24945 24946@item @emph{Real-Time Systems (Annex D)} 24947 24948The Real-Time Systems Annex is fully implemented. 24949 24950@item @emph{Distributed Systems (Annex E)} 24951 24952Stub generation is fully implemented in the GNAT compiler. In addition, 24953a complete compatible PCS is available as part of the GLADE system, 24954a separate product. When the two 24955products are used in conjunction, this annex is fully implemented. 24956 24957@item @emph{Information Systems (Annex F)} 24958 24959The Information Systems annex is fully implemented. 24960 24961@item @emph{Numerics (Annex G)} 24962 24963The Numerics Annex is fully implemented. 24964 24965@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 24966 24967The Safety and Security Annex (termed the High-Integrity Systems Annex 24968in Ada 2005) is fully implemented. 24969@end table 24970 24971@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 24972@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{3bf}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{3c0} 24973@chapter Implementation of Specific Ada Features 24974 24975 24976This chapter describes the GNAT implementation of several Ada language 24977facilities. 24978 24979@menu 24980* Machine Code Insertions:: 24981* GNAT Implementation of Tasking:: 24982* GNAT Implementation of Shared Passive Packages:: 24983* Code Generation for Array Aggregates:: 24984* The Size of Discriminated Records with Default Discriminants:: 24985* Strict Conformance to the Ada Reference Manual:: 24986 24987@end menu 24988 24989@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 24990@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{125}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{3c1} 24991@section Machine Code Insertions 24992 24993 24994@geindex Machine Code insertions 24995 24996Package @cite{Machine_Code} provides machine code support as described 24997in the Ada Reference Manual in two separate forms: 24998 24999 25000@itemize * 25001 25002@item 25003Machine code statements, consisting of qualified expressions that 25004fit the requirements of RM section 13.8. 25005 25006@item 25007An intrinsic callable procedure, providing an alternative mechanism of 25008including machine instructions in a subprogram. 25009@end itemize 25010 25011The two features are similar, and both are closely related to the mechanism 25012provided by the asm instruction in the GNU C compiler. Full understanding 25013and use of the facilities in this package requires understanding the asm 25014instruction, see the section on Extended Asm in 25015@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 25016 25017Calls to the function @cite{Asm} and the procedure @cite{Asm} have identical 25018semantic restrictions and effects as described below. Both are provided so 25019that the procedure call can be used as a statement, and the function call 25020can be used to form a code_statement. 25021 25022Consider this C @cite{asm} instruction: 25023 25024@example 25025asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 25026@end example 25027 25028The equivalent can be written for GNAT as: 25029 25030@example 25031Asm ("fsinx %1 %0", 25032 My_Float'Asm_Output ("=f", result), 25033 My_Float'Asm_Input ("f", angle)); 25034@end example 25035 25036The first argument to @cite{Asm} is the assembler template, and is 25037identical to what is used in GNU C. This string must be a static 25038expression. The second argument is the output operand list. It is 25039either a single @cite{Asm_Output} attribute reference, or a list of such 25040references enclosed in parentheses (technically an array aggregate of 25041such references). 25042 25043The @cite{Asm_Output} attribute denotes a function that takes two 25044parameters. The first is a string, the second is the name of a variable 25045of the type designated by the attribute prefix. The first (string) 25046argument is required to be a static expression and designates the 25047constraint (see the section on Constraints in 25048@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 25049for the parameter; e.g., what kind of register is required. The second 25050argument is the variable to be written or updated with the 25051result. The possible values for constraint are the same as those used in 25052the RTL, and are dependent on the configuration file used to build the 25053GCC back end. If there are no output operands, then this argument may 25054either be omitted, or explicitly given as @cite{No_Output_Operands}. 25055No support is provided for GNU C's symbolic names for output parameters. 25056 25057The second argument of @code{my_float'Asm_Output} functions as 25058though it were an @cite{out} parameter, which is a little curious, but 25059all names have the form of expressions, so there is no syntactic 25060irregularity, even though normally functions would not be permitted 25061@cite{out} parameters. The third argument is the list of input 25062operands. It is either a single @cite{Asm_Input} attribute reference, or 25063a list of such references enclosed in parentheses (technically an array 25064aggregate of such references). 25065 25066The @cite{Asm_Input} attribute denotes a function that takes two 25067parameters. The first is a string, the second is an expression of the 25068type designated by the prefix. The first (string) argument is required 25069to be a static expression, and is the constraint for the parameter, 25070(e.g., what kind of register is required). The second argument is the 25071value to be used as the input argument. The possible values for the 25072constraint are the same as those used in the RTL, and are dependent on 25073the configuration file used to built the GCC back end. 25074No support is provided for GNU C's symbolic names for input parameters. 25075 25076If there are no input operands, this argument may either be omitted, or 25077explicitly given as @cite{No_Input_Operands}. The fourth argument, not 25078present in the above example, is a list of register names, called the 25079@emph{clobber} argument. This argument, if given, must be a static string 25080expression, and is a space or comma separated list of names of registers 25081that must be considered destroyed as a result of the @cite{Asm} call. If 25082this argument is the null string (the default value), then the code 25083generator assumes that no additional registers are destroyed. 25084In addition to registers, the special clobbers @cite{memory} and 25085@cite{cc} as described in the GNU C docs are both supported. 25086 25087The fifth argument, not present in the above example, called the 25088@emph{volatile} argument, is by default @cite{False}. It can be set to 25089the literal value @cite{True} to indicate to the code generator that all 25090optimizations with respect to the instruction specified should be 25091suppressed, and in particular an instruction that has outputs 25092will still be generated, even if none of the outputs are 25093used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 25094for the full description. 25095Generally it is strongly advisable to use Volatile for any ASM statement 25096that is missing either input or output operands or to avoid unwanted 25097optimizations. A warning is generated if this advice is not followed. 25098 25099No support is provided for GNU C's @cite{asm goto} feature. 25100 25101The @cite{Asm} subprograms may be used in two ways. First the procedure 25102forms can be used anywhere a procedure call would be valid, and 25103correspond to what the RM calls 'intrinsic' routines. Such calls can 25104be used to intersperse machine instructions with other Ada statements. 25105Second, the function forms, which return a dummy value of the limited 25106private type @cite{Asm_Insn}, can be used in code statements, and indeed 25107this is the only context where such calls are allowed. Code statements 25108appear as aggregates of the form: 25109 25110@example 25111Asm_Insn'(Asm (...)); 25112Asm_Insn'(Asm_Volatile (...)); 25113@end example 25114 25115In accordance with RM rules, such code statements are allowed only 25116within subprograms whose entire body consists of such statements. It is 25117not permissible to intermix such statements with other Ada statements. 25118 25119Typically the form using intrinsic procedure calls is more convenient 25120and more flexible. The code statement form is provided to meet the RM 25121suggestion that such a facility should be made available. The following 25122is the exact syntax of the call to @cite{Asm}. As usual, if named notation 25123is used, the arguments may be given in arbitrary order, following the 25124normal rules for use of positional and named arguments: 25125 25126@example 25127ASM_CALL ::= Asm ( 25128 [Template =>] static_string_EXPRESSION 25129 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 25130 [,[Inputs =>] INPUT_OPERAND_LIST ] 25131 [,[Clobber =>] static_string_EXPRESSION ] 25132 [,[Volatile =>] static_boolean_EXPRESSION] ) 25133 25134OUTPUT_OPERAND_LIST ::= 25135 [PREFIX.]No_Output_Operands 25136| OUTPUT_OPERAND_ATTRIBUTE 25137| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 25138 25139OUTPUT_OPERAND_ATTRIBUTE ::= 25140 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 25141 25142INPUT_OPERAND_LIST ::= 25143 [PREFIX.]No_Input_Operands 25144| INPUT_OPERAND_ATTRIBUTE 25145| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 25146 25147INPUT_OPERAND_ATTRIBUTE ::= 25148 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 25149@end example 25150 25151The identifiers @cite{No_Input_Operands} and @cite{No_Output_Operands} 25152are declared in the package @cite{Machine_Code} and must be referenced 25153according to normal visibility rules. In particular if there is no 25154@cite{use} clause for this package, then appropriate package name 25155qualification is required. 25156 25157@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 25158@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{3c2}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{3c3} 25159@section GNAT Implementation of Tasking 25160 25161 25162This chapter outlines the basic GNAT approach to tasking (in particular, 25163a multi-layered library for portability) and discusses issues related 25164to compliance with the Real-Time Systems Annex. 25165 25166@menu 25167* Mapping Ada Tasks onto the Underlying Kernel Threads:: 25168* Ensuring Compliance with the Real-Time Annex:: 25169 25170@end menu 25171 25172@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 25173@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{3c4}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{3c5} 25174@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 25175 25176 25177GNAT's run-time support comprises two layers: 25178 25179 25180@itemize * 25181 25182@item 25183GNARL (GNAT Run-time Layer) 25184 25185@item 25186GNULL (GNAT Low-level Library) 25187@end itemize 25188 25189In GNAT, Ada's tasking services rely on a platform and OS independent 25190layer known as GNARL. This code is responsible for implementing the 25191correct semantics of Ada's task creation, rendezvous, protected 25192operations etc. 25193 25194GNARL decomposes Ada's tasking semantics into simpler lower level 25195operations such as create a thread, set the priority of a thread, 25196yield, create a lock, lock/unlock, etc. The spec for these low-level 25197operations constitutes GNULLI, the GNULL Interface. This interface is 25198directly inspired from the POSIX real-time API. 25199 25200If the underlying executive or OS implements the POSIX standard 25201faithfully, the GNULL Interface maps as is to the services offered by 25202the underlying kernel. Otherwise, some target dependent glue code maps 25203the services offered by the underlying kernel to the semantics expected 25204by GNARL. 25205 25206Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 25207key point is that each Ada task is mapped on a thread in the underlying 25208kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 25209 25210In addition Ada task priorities map onto the underlying thread priorities. 25211Mapping Ada tasks onto the underlying kernel threads has several advantages: 25212 25213 25214@itemize * 25215 25216@item 25217The underlying scheduler is used to schedule the Ada tasks. This 25218makes Ada tasks as efficient as kernel threads from a scheduling 25219standpoint. 25220 25221@item 25222Interaction with code written in C containing threads is eased 25223since at the lowest level Ada tasks and C threads map onto the same 25224underlying kernel concept. 25225 25226@item 25227When an Ada task is blocked during I/O the remaining Ada tasks are 25228able to proceed. 25229 25230@item 25231On multiprocessor systems Ada tasks can execute in parallel. 25232@end itemize 25233 25234Some threads libraries offer a mechanism to fork a new process, with the 25235child process duplicating the threads from the parent. 25236GNAT does not 25237support this functionality when the parent contains more than one task. 25238 25239@geindex Forking a new process 25240 25241@node Ensuring Compliance with the Real-Time Annex,,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 25242@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{3c6}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{3c7} 25243@subsection Ensuring Compliance with the Real-Time Annex 25244 25245 25246@geindex Real-Time Systems Annex compliance 25247 25248Although mapping Ada tasks onto 25249the underlying threads has significant advantages, it does create some 25250complications when it comes to respecting the scheduling semantics 25251specified in the real-time annex (Annex D). 25252 25253For instance the Annex D requirement for the @cite{FIFO_Within_Priorities} 25254scheduling policy states: 25255 25256@quotation 25257 25258@emph{When the active priority of a ready task that is not running 25259changes, or the setting of its base priority takes effect, the 25260task is removed from the ready queue for its old active priority 25261and is added at the tail of the ready queue for its new active 25262priority, except in the case where the active priority is lowered 25263due to the loss of inherited priority, in which case the task is 25264added at the head of the ready queue for its new active priority.} 25265@end quotation 25266 25267While most kernels do put tasks at the end of the priority queue when 25268a task changes its priority, (which respects the main 25269FIFO_Within_Priorities requirement), almost none keep a thread at the 25270beginning of its priority queue when its priority drops from the loss 25271of inherited priority. 25272 25273As a result most vendors have provided incomplete Annex D implementations. 25274 25275The GNAT run-time, has a nice cooperative solution to this problem 25276which ensures that accurate FIFO_Within_Priorities semantics are 25277respected. 25278 25279The principle is as follows. When an Ada task T is about to start 25280running, it checks whether some other Ada task R with the same 25281priority as T has been suspended due to the loss of priority 25282inheritance. If this is the case, T yields and is placed at the end of 25283its priority queue. When R arrives at the front of the queue it 25284executes. 25285 25286Note that this simple scheme preserves the relative order of the tasks 25287that were ready to execute in the priority queue where R has been 25288placed at the end. 25289 25290@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 25291@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{3c8}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{3c9} 25292@section GNAT Implementation of Shared Passive Packages 25293 25294 25295@geindex Shared passive packages 25296 25297GNAT fully implements the 25298@geindex pragma Shared_Passive 25299pragma 25300@cite{Shared_Passive} for 25301the purpose of designating shared passive packages. 25302This allows the use of passive partitions in the 25303context described in the Ada Reference Manual; i.e., for communication 25304between separate partitions of a distributed application using the 25305features in Annex E. 25306 25307@geindex Annex E 25308 25309@geindex Distribution Systems Annex 25310 25311However, the implementation approach used by GNAT provides for more 25312extensive usage as follows: 25313 25314 25315@table @asis 25316 25317@item @emph{Communication between separate programs} 25318 25319This allows separate programs to access the data in passive 25320partitions, using protected objects for synchronization where 25321needed. The only requirement is that the two programs have a 25322common shared file system. It is even possible for programs 25323running on different machines with different architectures 25324(e.g., different endianness) to communicate via the data in 25325a passive partition. 25326 25327@item @emph{Persistence between program runs} 25328 25329The data in a passive package can persist from one run of a 25330program to another, so that a later program sees the final 25331values stored by a previous run of the same program. 25332@end table 25333 25334The implementation approach used is to store the data in files. A 25335separate stream file is created for each object in the package, and 25336an access to an object causes the corresponding file to be read or 25337written. 25338 25339@geindex SHARED_MEMORY_DIRECTORY environment variable 25340 25341The environment variable @cite{SHARED_MEMORY_DIRECTORY} should be 25342set to the directory to be used for these files. 25343The files in this directory 25344have names that correspond to their fully qualified names. For 25345example, if we have the package 25346 25347@example 25348package X is 25349 pragma Shared_Passive (X); 25350 Y : Integer; 25351 Z : Float; 25352end X; 25353@end example 25354 25355and the environment variable is set to @cite{/stemp/}, then the files created 25356will have the names: 25357 25358@example 25359/stemp/x.y 25360/stemp/x.z 25361@end example 25362 25363These files are created when a value is initially written to the object, and 25364the files are retained until manually deleted. This provides the persistence 25365semantics. If no file exists, it means that no partition has assigned a value 25366to the variable; in this case the initial value declared in the package 25367will be used. This model ensures that there are no issues in synchronizing 25368the elaboration process, since elaboration of passive packages elaborates the 25369initial values, but does not create the files. 25370 25371The files are written using normal @cite{Stream_IO} access. 25372If you want to be able 25373to communicate between programs or partitions running on different 25374architectures, then you should use the XDR versions of the stream attribute 25375routines, since these are architecture independent. 25376 25377If active synchronization is required for access to the variables in the 25378shared passive package, then as described in the Ada Reference Manual, the 25379package may contain protected objects used for this purpose. In this case 25380a lock file (whose name is @code{___lock} (three underscores) 25381is created in the shared memory directory. 25382 25383@geindex ___lock file (for shared passive packages) 25384 25385This is used to provide the required locking 25386semantics for proper protected object synchronization. 25387 25388GNAT supports shared passive packages on all platforms 25389except for OpenVMS. 25390 25391@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 25392@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{3ca}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{3cb} 25393@section Code Generation for Array Aggregates 25394 25395 25396Aggregates have a rich syntax and allow the user to specify the values of 25397complex data structures by means of a single construct. As a result, the 25398code generated for aggregates can be quite complex and involve loops, case 25399statements and multiple assignments. In the simplest cases, however, the 25400compiler will recognize aggregates whose components and constraints are 25401fully static, and in those cases the compiler will generate little or no 25402executable code. The following is an outline of the code that GNAT generates 25403for various aggregate constructs. For further details, you will find it 25404useful to examine the output produced by the -gnatG flag to see the expanded 25405source that is input to the code generator. You may also want to examine 25406the assembly code generated at various levels of optimization. 25407 25408The code generated for aggregates depends on the context, the component values, 25409and the type. In the context of an object declaration the code generated is 25410generally simpler than in the case of an assignment. As a general rule, static 25411component values and static subtypes also lead to simpler code. 25412 25413@menu 25414* Static constant aggregates with static bounds:: 25415* Constant aggregates with unconstrained nominal types:: 25416* Aggregates with static bounds:: 25417* Aggregates with nonstatic bounds:: 25418* Aggregates in assignment statements:: 25419 25420@end menu 25421 25422@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 25423@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{3cc}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{3cd} 25424@subsection Static constant aggregates with static bounds 25425 25426 25427For the declarations: 25428 25429@example 25430type One_Dim is array (1..10) of integer; 25431ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 25432@end example 25433 25434GNAT generates no executable code: the constant ar0 is placed in static memory. 25435The same is true for constant aggregates with named associations: 25436 25437@example 25438Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 25439Cr3 : constant One_Dim := (others => 7777); 25440@end example 25441 25442The same is true for multidimensional constant arrays such as: 25443 25444@example 25445type two_dim is array (1..3, 1..3) of integer; 25446Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 25447@end example 25448 25449The same is true for arrays of one-dimensional arrays: the following are 25450static: 25451 25452@example 25453type ar1b is array (1..3) of boolean; 25454type ar_ar is array (1..3) of ar1b; 25455None : constant ar1b := (others => false); -- fully static 25456None2 : constant ar_ar := (1..3 => None); -- fully static 25457@end example 25458 25459However, for multidimensional aggregates with named associations, GNAT will 25460generate assignments and loops, even if all associations are static. The 25461following two declarations generate a loop for the first dimension, and 25462individual component assignments for the second dimension: 25463 25464@example 25465Zero1: constant two_dim := (1..3 => (1..3 => 0)); 25466Zero2: constant two_dim := (others => (others => 0)); 25467@end example 25468 25469@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 25470@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{3ce}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{3cf} 25471@subsection Constant aggregates with unconstrained nominal types 25472 25473 25474In such cases the aggregate itself establishes the subtype, so that 25475associations with @cite{others} cannot be used. GNAT determines the 25476bounds for the actual subtype of the aggregate, and allocates the 25477aggregate statically as well. No code is generated for the following: 25478 25479@example 25480type One_Unc is array (natural range <>) of integer; 25481Cr_Unc : constant One_Unc := (12,24,36); 25482@end example 25483 25484@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 25485@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{3d0}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{3d1} 25486@subsection Aggregates with static bounds 25487 25488 25489In all previous examples the aggregate was the initial (and immutable) value 25490of a constant. If the aggregate initializes a variable, then code is generated 25491for it as a combination of individual assignments and loops over the target 25492object. The declarations 25493 25494@example 25495Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 25496Cr_Var2 : One_Dim := (others > -1); 25497@end example 25498 25499generate the equivalent of 25500 25501@example 25502Cr_Var1 (1) := 2; 25503Cr_Var1 (2) := 3; 25504Cr_Var1 (3) := 5; 25505Cr_Var1 (4) := 11; 25506 25507for I in Cr_Var2'range loop 25508 Cr_Var2 (I) := -1; 25509end loop; 25510@end example 25511 25512@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 25513@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{3d2}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{3d3} 25514@subsection Aggregates with nonstatic bounds 25515 25516 25517If the bounds of the aggregate are not statically compatible with the bounds 25518of the nominal subtype of the target, then constraint checks have to be 25519generated on the bounds. For a multidimensional array, constraint checks may 25520have to be applied to sub-arrays individually, if they do not have statically 25521compatible subtypes. 25522 25523@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 25524@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{3d4}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{3d5} 25525@subsection Aggregates in assignment statements 25526 25527 25528In general, aggregate assignment requires the construction of a temporary, 25529and a copy from the temporary to the target of the assignment. This is because 25530it is not always possible to convert the assignment into a series of individual 25531component assignments. For example, consider the simple case: 25532 25533@example 25534A := (A(2), A(1)); 25535@end example 25536 25537This cannot be converted into: 25538 25539@example 25540A(1) := A(2); 25541A(2) := A(1); 25542@end example 25543 25544So the aggregate has to be built first in a separate location, and then 25545copied into the target. GNAT recognizes simple cases where this intermediate 25546step is not required, and the assignments can be performed in place, directly 25547into the target. The following sufficient criteria are applied: 25548 25549 25550@itemize * 25551 25552@item 25553The bounds of the aggregate are static, and the associations are static. 25554 25555@item 25556The components of the aggregate are static constants, names of 25557simple variables that are not renamings, or expressions not involving 25558indexed components whose operands obey these rules. 25559@end itemize 25560 25561If any of these conditions are violated, the aggregate will be built in 25562a temporary (created either by the front-end or the code generator) and then 25563that temporary will be copied onto the target. 25564 25565@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 25566@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{3d6}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{3d7} 25567@section The Size of Discriminated Records with Default Discriminants 25568 25569 25570If a discriminated type @cite{T} has discriminants with default values, it is 25571possible to declare an object of this type without providing an explicit 25572constraint: 25573 25574@example 25575type Size is range 1..100; 25576 25577type Rec (D : Size := 15) is record 25578 Name : String (1..D); 25579end T; 25580 25581Word : Rec; 25582@end example 25583 25584Such an object is said to be @emph{unconstrained}. 25585The discriminant of the object 25586can be modified by a full assignment to the object, as long as it preserves the 25587relation between the value of the discriminant, and the value of the components 25588that depend on it: 25589 25590@example 25591Word := (3, "yes"); 25592 25593Word := (5, "maybe"); 25594 25595Word := (5, "no"); -- raises Constraint_Error 25596@end example 25597 25598In order to support this behavior efficiently, an unconstrained object is 25599given the maximum size that any value of the type requires. In the case 25600above, @cite{Word} has storage for the discriminant and for 25601a @cite{String} of length 100. 25602It is important to note that unconstrained objects do not require dynamic 25603allocation. It would be an improper implementation to place on the heap those 25604components whose size depends on discriminants. (This improper implementation 25605was used by some Ada83 compilers, where the @cite{Name} component above 25606would have 25607been stored as a pointer to a dynamic string). Following the principle that 25608dynamic storage management should never be introduced implicitly, 25609an Ada compiler should reserve the full size for an unconstrained declared 25610object, and place it on the stack. 25611 25612This maximum size approach 25613has been a source of surprise to some users, who expect the default 25614values of the discriminants to determine the size reserved for an 25615unconstrained object: "If the default is 15, why should the object occupy 25616a larger size?" 25617The answer, of course, is that the discriminant may be later modified, 25618and its full range of values must be taken into account. This is why the 25619declaration: 25620 25621@example 25622type Rec (D : Positive := 15) is record 25623 Name : String (1..D); 25624end record; 25625 25626Too_Large : Rec; 25627@end example 25628 25629is flagged by the compiler with a warning: 25630an attempt to create @cite{Too_Large} will raise @cite{Storage_Error}, 25631because the required size includes @cite{Positive'Last} 25632bytes. As the first example indicates, the proper approach is to declare an 25633index type of 'reasonable' range so that unconstrained objects are not too 25634large. 25635 25636One final wrinkle: if the object is declared to be @cite{aliased}, or if it is 25637created in the heap by means of an allocator, then it is @emph{not} 25638unconstrained: 25639it is constrained by the default values of the discriminants, and those values 25640cannot be modified by full assignment. This is because in the presence of 25641aliasing all views of the object (which may be manipulated by different tasks, 25642say) must be consistent, so it is imperative that the object, once created, 25643remain invariant. 25644 25645@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features 25646@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{3d8}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{3d9} 25647@section Strict Conformance to the Ada Reference Manual 25648 25649 25650The dynamic semantics defined by the Ada Reference Manual impose a set of 25651run-time checks to be generated. By default, the GNAT compiler will insert many 25652run-time checks into the compiled code, including most of those required by the 25653Ada Reference Manual. However, there are two checks that are not enabled in 25654the default mode for efficiency reasons: checks for access before elaboration 25655on subprogram calls, and stack overflow checking (most operating systems do not 25656perform this check by default). 25657 25658Strict conformance to the Ada Reference Manual can be achieved by adding two 25659compiler options for dynamic checks for access-before-elaboration on subprogram 25660calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 25661(@emph{-fstack-check}). 25662 25663Note that the result of a floating point arithmetic operation in overflow and 25664invalid situations, when the @cite{Machine_Overflows} attribute of the result 25665type is @cite{False}, is to generate IEEE NaN and infinite values. This is the 25666case for machines compliant with the IEEE floating-point standard, but on 25667machines that are not fully compliant with this standard, such as Alpha, the 25668@emph{-mieee} compiler flag must be used for achieving IEEE confirming 25669behavior (although at the cost of a significant performance penalty), so 25670infinite and NaN values are properly generated. 25671 25672@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top 25673@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{3da}@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{3db} 25674@chapter Implementation of Ada 2012 Features 25675 25676 25677@geindex Ada 2012 implementation status 25678 25679@geindex -gnat12 option (gcc) 25680 25681@geindex pragma Ada_2012 25682 25683@geindex configuration pragma Ada_2012 25684 25685@geindex Ada_2012 configuration pragma 25686 25687This chapter contains a complete list of Ada 2012 features that have been 25688implemented. 25689Generally, these features are only 25690available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 25691which is the default behavior, 25692or if the configuration pragma @cite{Ada_2012} is used. 25693 25694However, new pragmas, attributes, and restrictions are 25695unconditionally available, since the Ada 95 standard allows the addition of 25696new pragmas, attributes, and restrictions (there are exceptions, which are 25697documented in the individual descriptions), and also certain packages 25698were made available in earlier versions of Ada. 25699 25700An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 25701This date shows the implementation date of the feature. Any wavefront 25702subsequent to this date will contain the indicated feature, as will any 25703subsequent releases. A date of 0000-00-00 means that GNAT has always 25704implemented the feature, or implemented it as soon as it appeared as a 25705binding interpretation. 25706 25707Each feature corresponds to an Ada Issue ('AI') approved by the Ada 25708standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 25709The features are ordered based on the relevant sections of the Ada 25710Reference Manual ("RM"). When a given AI relates to multiple points 25711in the RM, the earliest is used. 25712 25713A complete description of the AIs may be found in 25714@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 25715 25716@geindex AI-0176 (Ada 2012 feature) 25717 25718 25719@itemize * 25720 25721@item 25722@emph{AI-0176 Quantified expressions (2010-09-29)} 25723 25724Both universally and existentially quantified expressions are implemented. 25725They use the new syntax for iterators proposed in AI05-139-2, as well as 25726the standard Ada loop syntax. 25727 25728RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 25729@end itemize 25730 25731@geindex AI-0079 (Ada 2012 feature) 25732 25733 25734@itemize * 25735 25736@item 25737@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 25738 25739Wide characters in the unicode category @emph{other_format} are now allowed in 25740source programs between tokens, but not within a token such as an identifier. 25741 25742RM References: 2.01 (4/2) 2.02 (7) 25743@end itemize 25744 25745@geindex AI-0091 (Ada 2012 feature) 25746 25747 25748@itemize * 25749 25750@item 25751@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 25752 25753Wide characters in the unicode category @emph{other_format} are not permitted 25754within an identifier, since this can be a security problem. The error 25755message for this case has been improved to be more specific, but GNAT has 25756never allowed such characters to appear in identifiers. 25757 25758RM 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) 25759@end itemize 25760 25761@geindex AI-0100 (Ada 2012 feature) 25762 25763 25764@itemize * 25765 25766@item 25767@emph{AI-0100 Placement of pragmas (2010-07-01)} 25768 25769This AI is an earlier version of AI-163. It simplifies the rules 25770for legal placement of pragmas. In the case of lists that allow pragmas, if 25771the list may have no elements, then the list may consist solely of pragmas. 25772 25773RM References: 2.08 (7) 25774@end itemize 25775 25776@geindex AI-0163 (Ada 2012 feature) 25777 25778 25779@itemize * 25780 25781@item 25782@emph{AI-0163 Pragmas in place of null (2010-07-01)} 25783 25784A statement sequence may be composed entirely of pragmas. It is no longer 25785necessary to add a dummy @cite{null} statement to make the sequence legal. 25786 25787RM References: 2.08 (7) 2.08 (16) 25788@end itemize 25789 25790@geindex AI-0080 (Ada 2012 feature) 25791 25792 25793@itemize * 25794 25795@item 25796@emph{AI-0080 'View of' not needed if clear from context (0000-00-00)} 25797 25798This is an editorial change only, described as non-testable in the AI. 25799 25800RM References: 3.01 (7) 25801@end itemize 25802 25803@geindex AI-0183 (Ada 2012 feature) 25804 25805 25806@itemize * 25807 25808@item 25809@emph{AI-0183 Aspect specifications (2010-08-16)} 25810 25811Aspect specifications have been fully implemented except for pre and post- 25812conditions, and type invariants, which have their own separate AI's. All 25813forms of declarations listed in the AI are supported. The following is a 25814list of the aspects supported (with GNAT implementation aspects marked) 25815@end itemize 25816 25817 25818@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 25819@headitem 25820 25821Supported Aspect 25822 25823@tab 25824 25825Source 25826 25827@item 25828 25829@cite{Ada_2005} 25830 25831@tab 25832 25833-- GNAT 25834 25835@item 25836 25837@cite{Ada_2012} 25838 25839@tab 25840 25841-- GNAT 25842 25843@item 25844 25845@cite{Address} 25846 25847@tab 25848 25849@item 25850 25851@cite{Alignment} 25852 25853@tab 25854 25855@item 25856 25857@cite{Atomic} 25858 25859@tab 25860 25861@item 25862 25863@cite{Atomic_Components} 25864 25865@tab 25866 25867@item 25868 25869@cite{Bit_Order} 25870 25871@tab 25872 25873@item 25874 25875@cite{Component_Size} 25876 25877@tab 25878 25879@item 25880 25881@cite{Contract_Cases} 25882 25883@tab 25884 25885-- GNAT 25886 25887@item 25888 25889@cite{Discard_Names} 25890 25891@tab 25892 25893@item 25894 25895@cite{External_Tag} 25896 25897@tab 25898 25899@item 25900 25901@cite{Favor_Top_Level} 25902 25903@tab 25904 25905-- GNAT 25906 25907@item 25908 25909@cite{Inline} 25910 25911@tab 25912 25913@item 25914 25915@cite{Inline_Always} 25916 25917@tab 25918 25919-- GNAT 25920 25921@item 25922 25923@cite{Invariant} 25924 25925@tab 25926 25927-- GNAT 25928 25929@item 25930 25931@cite{Machine_Radix} 25932 25933@tab 25934 25935@item 25936 25937@cite{No_Return} 25938 25939@tab 25940 25941@item 25942 25943@cite{Object_Size} 25944 25945@tab 25946 25947-- GNAT 25948 25949@item 25950 25951@cite{Pack} 25952 25953@tab 25954 25955@item 25956 25957@cite{Persistent_BSS} 25958 25959@tab 25960 25961-- GNAT 25962 25963@item 25964 25965@cite{Post} 25966 25967@tab 25968 25969@item 25970 25971@cite{Pre} 25972 25973@tab 25974 25975@item 25976 25977@cite{Predicate} 25978 25979@tab 25980 25981@item 25982 25983@cite{Preelaborable_Initialization} 25984 25985@tab 25986 25987@item 25988 25989@cite{Pure_Function} 25990 25991@tab 25992 25993-- GNAT 25994 25995@item 25996 25997@cite{Remote_Access_Type} 25998 25999@tab 26000 26001-- GNAT 26002 26003@item 26004 26005@cite{Shared} 26006 26007@tab 26008 26009-- GNAT 26010 26011@item 26012 26013@cite{Size} 26014 26015@tab 26016 26017@item 26018 26019@cite{Storage_Pool} 26020 26021@tab 26022 26023@item 26024 26025@cite{Storage_Size} 26026 26027@tab 26028 26029@item 26030 26031@cite{Stream_Size} 26032 26033@tab 26034 26035@item 26036 26037@cite{Suppress} 26038 26039@tab 26040 26041@item 26042 26043@cite{Suppress_Debug_Info} 26044 26045@tab 26046 26047-- GNAT 26048 26049@item 26050 26051@cite{Test_Case} 26052 26053@tab 26054 26055-- GNAT 26056 26057@item 26058 26059@cite{Thread_Local_Storage} 26060 26061@tab 26062 26063-- GNAT 26064 26065@item 26066 26067@cite{Type_Invariant} 26068 26069@tab 26070 26071@item 26072 26073@cite{Unchecked_Union} 26074 26075@tab 26076 26077@item 26078 26079@cite{Universal_Aliasing} 26080 26081@tab 26082 26083-- GNAT 26084 26085@item 26086 26087@cite{Unmodified} 26088 26089@tab 26090 26091-- GNAT 26092 26093@item 26094 26095@cite{Unreferenced} 26096 26097@tab 26098 26099-- GNAT 26100 26101@item 26102 26103@cite{Unreferenced_Objects} 26104 26105@tab 26106 26107-- GNAT 26108 26109@item 26110 26111@cite{Unsuppress} 26112 26113@tab 26114 26115@item 26116 26117@cite{Value_Size} 26118 26119@tab 26120 26121-- GNAT 26122 26123@item 26124 26125@cite{Volatile} 26126 26127@tab 26128 26129@item 26130 26131@cite{Volatile_Components} 26132 26133@tab 26134 26135@item 26136 26137@cite{Warnings} 26138 26139@tab 26140 26141-- GNAT 26142 26143@end multitable 26144 26145 26146@quotation 26147 26148Note that for aspects with an expression, e.g. @cite{Size}, the expression is 26149treated like a default expression (visibility is analyzed at the point of 26150occurrence of the aspect, but evaluation of the expression occurs at the 26151freeze point of the entity involved). 26152 26153RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 261543.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 26155(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 261569.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2615712.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2615813.03.01 (0) 26159@end quotation 26160 26161@geindex AI-0128 (Ada 2012 feature) 26162 26163 26164@itemize * 26165 26166@item 26167@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 26168 26169If an equality operator ("=") is declared for a type, then the implicitly 26170declared inequality operator ("/=") is a primitive operation of the type. 26171This is the only reasonable interpretation, and is the one always implemented 26172by GNAT, but the RM was not entirely clear in making this point. 26173 26174RM References: 3.02.03 (6) 6.06 (6) 26175@end itemize 26176 26177@geindex AI-0003 (Ada 2012 feature) 26178 26179 26180@itemize * 26181 26182@item 26183@emph{AI-0003 Qualified expressions as names (2010-07-11)} 26184 26185In Ada 2012, a qualified expression is considered to be syntactically a name, 26186meaning that constructs such as @cite{A'(F(X)).B} are now legal. This is 26187useful in disambiguating some cases of overloading. 26188 26189RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 261905.04 (7) 26191@end itemize 26192 26193@geindex AI-0120 (Ada 2012 feature) 26194 26195 26196@itemize * 26197 26198@item 26199@emph{AI-0120 Constant instance of protected object (0000-00-00)} 26200 26201This is an RM editorial change only. The section that lists objects that are 26202constant failed to include the current instance of a protected object 26203within a protected function. This has always been treated as a constant 26204in GNAT. 26205 26206RM References: 3.03 (21) 26207@end itemize 26208 26209@geindex AI-0008 (Ada 2012 feature) 26210 26211 26212@itemize * 26213 26214@item 26215@emph{AI-0008 General access to constrained objects (0000-00-00)} 26216 26217The wording in the RM implied that if you have a general access to a 26218constrained object, it could be used to modify the discriminants. This was 26219obviously not intended. @cite{Constraint_Error} should be raised, and GNAT 26220has always done so in this situation. 26221 26222RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 26223@end itemize 26224 26225@geindex AI-0093 (Ada 2012 feature) 26226 26227 26228@itemize * 26229 26230@item 26231@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 26232 26233This is an editorial change only, to make more widespread use of the Ada 2012 26234'immutably limited'. 26235 26236RM References: 3.03 (23.4/3) 26237@end itemize 26238 26239@geindex AI-0096 (Ada 2012 feature) 26240 26241 26242@itemize * 26243 26244@item 26245@emph{AI-0096 Deriving from formal private types (2010-07-20)} 26246 26247In general it is illegal for a type derived from a formal limited type to be 26248nonlimited. This AI makes an exception to this rule: derivation is legal 26249if it appears in the private part of the generic, and the formal type is not 26250tagged. If the type is tagged, the legality check must be applied to the 26251private part of the package. 26252 26253RM References: 3.04 (5.1/2) 6.02 (7) 26254@end itemize 26255 26256@geindex AI-0181 (Ada 2012 feature) 26257 26258 26259@itemize * 26260 26261@item 26262@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 26263 26264From Ada 2005 on, soft hyphen is considered a non-graphic character, which 26265means that it has a special name (@cite{SOFT_HYPHEN}) in conjunction with the 26266@cite{Image} and @cite{Value} attributes for the character types. Strictly 26267speaking this is an inconsistency with Ada 95, but in practice the use of 26268these attributes is so obscure that it will not cause problems. 26269 26270RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 26271@end itemize 26272 26273@geindex AI-0182 (Ada 2012 feature) 26274 26275 26276@itemize * 26277 26278@item 26279@emph{AI-0182 Additional forms for `Character'Value} (0000-00-00)` 26280 26281This AI allows @cite{Character'Value} to accept the string @cite{'?'} where 26282@cite{?} is any character including non-graphic control characters. GNAT has 26283always accepted such strings. It also allows strings such as 26284@cite{HEX_00000041} to be accepted, but GNAT does not take advantage of this 26285permission and raises @cite{Constraint_Error}, as is certainly still 26286permitted. 26287 26288RM References: 3.05 (56/2) 26289@end itemize 26290 26291@geindex AI-0214 (Ada 2012 feature) 26292 26293 26294@itemize * 26295 26296@item 26297@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 26298 26299Ada 2012 relaxes the restriction that forbids discriminants of tagged types 26300to have default expressions by allowing them when the type is limited. It 26301is often useful to define a default value for a discriminant even though 26302it can't be changed by assignment. 26303 26304RM References: 3.07 (9.1/2) 3.07.02 (3) 26305@end itemize 26306 26307@geindex AI-0102 (Ada 2012 feature) 26308 26309 26310@itemize * 26311 26312@item 26313@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 26314 26315It is illegal to assign an anonymous access constant to an anonymous access 26316variable. The RM did not have a clear rule to prevent this, but GNAT has 26317always generated an error for this usage. 26318 26319RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 26320@end itemize 26321 26322@geindex AI-0158 (Ada 2012 feature) 26323 26324 26325@itemize * 26326 26327@item 26328@emph{AI-0158 Generalizing membership tests (2010-09-16)} 26329 26330This AI extends the syntax of membership tests to simplify complex conditions 26331that can be expressed as membership in a subset of values of any type. It 26332introduces syntax for a list of expressions that may be used in loop contexts 26333as well. 26334 26335RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 26336@end itemize 26337 26338@geindex AI-0173 (Ada 2012 feature) 26339 26340 26341@itemize * 26342 26343@item 26344@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 26345 26346The function @cite{Ada.Tags.Type_Is_Abstract} returns @cite{True} if invoked 26347with the tag of an abstract type, and @cite{False} otherwise. 26348 26349RM References: 3.09 (7.4/2) 3.09 (12.4/2) 26350@end itemize 26351 26352@geindex AI-0076 (Ada 2012 feature) 26353 26354 26355@itemize * 26356 26357@item 26358@emph{AI-0076 function with controlling result (0000-00-00)} 26359 26360This is an editorial change only. The RM defines calls with controlling 26361results, but uses the term 'function with controlling result' without an 26362explicit definition. 26363 26364RM References: 3.09.02 (2/2) 26365@end itemize 26366 26367@geindex AI-0126 (Ada 2012 feature) 26368 26369 26370@itemize * 26371 26372@item 26373@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 26374 26375This AI clarifies dispatching rules, and simply confirms that dispatching 26376executes the operation of the parent type when there is no explicitly or 26377implicitly declared operation for the descendant type. This has always been 26378the case in all versions of GNAT. 26379 26380RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 26381@end itemize 26382 26383@geindex AI-0097 (Ada 2012 feature) 26384 26385 26386@itemize * 26387 26388@item 26389@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 26390 26391The RM as written implied that in some cases it was possible to create an 26392object of an abstract type, by having an abstract extension inherit a non- 26393abstract constructor from its parent type. This mistake has been corrected 26394in GNAT and in the RM, and this construct is now illegal. 26395 26396RM References: 3.09.03 (4/2) 26397@end itemize 26398 26399@geindex AI-0203 (Ada 2012 feature) 26400 26401 26402@itemize * 26403 26404@item 26405@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 26406 26407A return_subtype_indication cannot denote an abstract subtype. GNAT has never 26408permitted such usage. 26409 26410RM References: 3.09.03 (8/3) 26411@end itemize 26412 26413@geindex AI-0198 (Ada 2012 feature) 26414 26415 26416@itemize * 26417 26418@item 26419@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 26420 26421This AI resolves a conflict between two rules involving inherited abstract 26422operations and predefined operators. If a derived numeric type inherits 26423an abstract operator, it overrides the predefined one. This interpretation 26424was always the one implemented in GNAT. 26425 26426RM References: 3.09.03 (4/3) 26427@end itemize 26428 26429@geindex AI-0073 (Ada 2012 feature) 26430 26431 26432@itemize * 26433 26434@item 26435@emph{AI-0073 Functions returning abstract types (2010-07-10)} 26436 26437This AI covers a number of issues regarding returning abstract types. In 26438particular generic functions cannot have abstract result types or access 26439result types designated an abstract type. There are some other cases which 26440are detailed in the AI. Note that this binding interpretation has not been 26441retrofitted to operate before Ada 2012 mode, since it caused a significant 26442number of regressions. 26443 26444RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 26445@end itemize 26446 26447@geindex AI-0070 (Ada 2012 feature) 26448 26449 26450@itemize * 26451 26452@item 26453@emph{AI-0070 Elaboration of interface types (0000-00-00)} 26454 26455This is an editorial change only, there are no testable consequences short of 26456checking for the absence of generated code for an interface declaration. 26457 26458RM References: 3.09.04 (18/2) 26459@end itemize 26460 26461@geindex AI-0208 (Ada 2012 feature) 26462 26463 26464@itemize * 26465 26466@item 26467@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 26468 26469The wording in the Ada 2005 RM concerning characteristics of incomplete views 26470was incorrect and implied that some programs intended to be legal were now 26471illegal. GNAT had never considered such programs illegal, so it has always 26472implemented the intent of this AI. 26473 26474RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 26475@end itemize 26476 26477@geindex AI-0162 (Ada 2012 feature) 26478 26479 26480@itemize * 26481 26482@item 26483@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 26484 26485Incomplete types are made more useful by allowing them to be completed by 26486private types and private extensions. 26487 26488RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 26489@end itemize 26490 26491@geindex AI-0098 (Ada 2012 feature) 26492 26493 26494@itemize * 26495 26496@item 26497@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 26498 26499An unintentional omission in the RM implied some inconsistent restrictions on 26500the use of anonymous access to subprogram values. These restrictions were not 26501intentional, and have never been enforced by GNAT. 26502 26503RM References: 3.10.01 (6) 3.10.01 (9.2/2) 26504@end itemize 26505 26506@geindex AI-0199 (Ada 2012 feature) 26507 26508 26509@itemize * 26510 26511@item 26512@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 26513 26514A choice list in a record aggregate can include several components of 26515(distinct) anonymous access types as long as they have matching designated 26516subtypes. 26517 26518RM References: 4.03.01 (16) 26519@end itemize 26520 26521@geindex AI-0220 (Ada 2012 feature) 26522 26523 26524@itemize * 26525 26526@item 26527@emph{AI-0220 Needed components for aggregates (0000-00-00)} 26528 26529This AI addresses a wording problem in the RM that appears to permit some 26530complex cases of aggregates with nonstatic discriminants. GNAT has always 26531implemented the intended semantics. 26532 26533RM References: 4.03.01 (17) 26534@end itemize 26535 26536@geindex AI-0147 (Ada 2012 feature) 26537 26538 26539@itemize * 26540 26541@item 26542@emph{AI-0147 Conditional expressions (2009-03-29)} 26543 26544Conditional expressions are permitted. The form of such an expression is: 26545 26546@example 26547(if expr then expr @{elsif expr then expr@} [else expr]) 26548@end example 26549 26550The parentheses can be omitted in contexts where parentheses are present 26551anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 26552clause is omitted, @strong{else} @emph{True} is assumed; 26553thus @code{(if A then B)} is a way to conveniently represent 26554@emph{(A implies B)} in standard logic. 26555 26556RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 265574.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 26558@end itemize 26559 26560@geindex AI-0037 (Ada 2012 feature) 26561 26562 26563@itemize * 26564 26565@item 26566@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 26567 26568This AI confirms that an association of the form @cite{Indx => <>} in an 26569array aggregate must raise @cite{Constraint_Error} if @cite{Indx} 26570is out of range. The RM specified a range check on other associations, but 26571not when the value of the association was defaulted. GNAT has always inserted 26572a constraint check on the index value. 26573 26574RM References: 4.03.03 (29) 26575@end itemize 26576 26577@geindex AI-0123 (Ada 2012 feature) 26578 26579 26580@itemize * 26581 26582@item 26583@emph{AI-0123 Composability of equality (2010-04-13)} 26584 26585Equality of untagged record composes, so that the predefined equality for a 26586composite type that includes a component of some untagged record type 26587@cite{R} uses the equality operation of @cite{R} (which may be user-defined 26588or predefined). This makes the behavior of untagged records identical to that 26589of tagged types in this respect. 26590 26591This change is an incompatibility with previous versions of Ada, but it 26592corrects a non-uniformity that was often a source of confusion. Analysis of 26593a large number of industrial programs indicates that in those rare cases 26594where a composite type had an untagged record component with a user-defined 26595equality, either there was no use of the composite equality, or else the code 26596expected the same composability as for tagged types, and thus had a bug that 26597would be fixed by this change. 26598 26599RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 266008.05.04 (8) 26601@end itemize 26602 26603@geindex AI-0088 (Ada 2012 feature) 26604 26605 26606@itemize * 26607 26608@item 26609@emph{AI-0088 The value of exponentiation (0000-00-00)} 26610 26611This AI clarifies the equivalence rule given for the dynamic semantics of 26612exponentiation: the value of the operation can be obtained by repeated 26613multiplication, but the operation can be implemented otherwise (for example 26614using the familiar divide-by-two-and-square algorithm, even if this is less 26615accurate), and does not imply repeated reads of a volatile base. 26616 26617RM References: 4.05.06 (11) 26618@end itemize 26619 26620@geindex AI-0188 (Ada 2012 feature) 26621 26622 26623@itemize * 26624 26625@item 26626@emph{AI-0188 Case expressions (2010-01-09)} 26627 26628Case expressions are permitted. This allows use of constructs such as: 26629 26630@example 26631X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 26632@end example 26633 26634RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 26635@end itemize 26636 26637@geindex AI-0104 (Ada 2012 feature) 26638 26639 26640@itemize * 26641 26642@item 26643@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 26644 26645The assignment @code{Ptr := new not null Some_Ptr;} will raise 26646@code{Constraint_Error} because the default value of the allocated object is 26647@strong{null}. This useless construct is illegal in Ada 2012. 26648 26649RM References: 4.08 (2) 26650@end itemize 26651 26652@geindex AI-0157 (Ada 2012 feature) 26653 26654 26655@itemize * 26656 26657@item 26658@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 26659 26660Allocation and Deallocation from an empty storage pool (i.e. allocation or 26661deallocation of a pointer for which a static storage size clause of zero 26662has been given) is now illegal and is detected as such. GNAT 26663previously gave a warning but not an error. 26664 26665RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 26666@end itemize 26667 26668@geindex AI-0179 (Ada 2012 feature) 26669 26670 26671@itemize * 26672 26673@item 26674@emph{AI-0179 Statement not required after label (2010-04-10)} 26675 26676It is not necessary to have a statement following a label, so a label 26677can appear at the end of a statement sequence without the need for putting a 26678null statement afterwards, but it is not allowable to have only labels and 26679no real statements in a statement sequence. 26680 26681RM References: 5.01 (2) 26682@end itemize 26683 26684@geindex AI-0139-2 (Ada 2012 feature) 26685 26686 26687@itemize * 26688 26689@item 26690@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 26691 26692The new syntax for iterating over arrays and containers is now implemented. 26693Iteration over containers is for now limited to read-only iterators. Only 26694default iterators are supported, with the syntax: @cite{for Elem of C}. 26695 26696RM References: 5.05 26697@end itemize 26698 26699@geindex AI-0134 (Ada 2012 feature) 26700 26701 26702@itemize * 26703 26704@item 26705@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 26706 26707For full conformance, the profiles of anonymous-access-to-subprogram 26708parameters must match. GNAT has always enforced this rule. 26709 26710RM References: 6.03.01 (18) 26711@end itemize 26712 26713@geindex AI-0207 (Ada 2012 feature) 26714 26715 26716@itemize * 26717 26718@item 26719@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 26720 26721This AI confirms that access_to_constant indication must match for mode 26722conformance. This was implemented in GNAT when the qualifier was originally 26723introduced in Ada 2005. 26724 26725RM References: 6.03.01 (16/2) 26726@end itemize 26727 26728@geindex AI-0046 (Ada 2012 feature) 26729 26730 26731@itemize * 26732 26733@item 26734@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 26735 26736For full conformance, in the case of access parameters, the null exclusion 26737must match (either both or neither must have @code{not null}). 26738 26739RM References: 6.03.02 (18) 26740@end itemize 26741 26742@geindex AI-0118 (Ada 2012 feature) 26743 26744 26745@itemize * 26746 26747@item 26748@emph{AI-0118 The association of parameter associations (0000-00-00)} 26749 26750This AI clarifies the rules for named associations in subprogram calls and 26751generic instantiations. The rules have been in place since Ada 83. 26752 26753RM References: 6.04.01 (2) 12.03 (9) 26754@end itemize 26755 26756@geindex AI-0196 (Ada 2012 feature) 26757 26758 26759@itemize * 26760 26761@item 26762@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 26763 26764Null exclusion checks are not made for @cite{**out**} parameters when 26765evaluating the actual parameters. GNAT has never generated these checks. 26766 26767RM References: 6.04.01 (13) 26768@end itemize 26769 26770@geindex AI-0015 (Ada 2012 feature) 26771 26772 26773@itemize * 26774 26775@item 26776@emph{AI-0015 Constant return objects (0000-00-00)} 26777 26778The return object declared in an @emph{extended_return_statement} may be 26779declared constant. This was always intended, and GNAT has always allowed it. 26780 26781RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 267826.05 (5.7/2) 26783@end itemize 26784 26785@geindex AI-0032 (Ada 2012 feature) 26786 26787 26788@itemize * 26789 26790@item 26791@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 26792 26793If a function returns a class-wide type, the object of an extended return 26794statement can be declared with a specific type that is covered by the class- 26795wide type. This has been implemented in GNAT since the introduction of 26796extended returns. Note AI-0103 complements this AI by imposing matching 26797rules for constrained return types. 26798 26799RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 268006.05 (8/2) 26801@end itemize 26802 26803@geindex AI-0103 (Ada 2012 feature) 26804 26805 26806@itemize * 26807 26808@item 26809@emph{AI-0103 Static matching for extended return (2010-07-23)} 26810 26811If the return subtype of a function is an elementary type or a constrained 26812type, the subtype indication in an extended return statement must match 26813statically this return subtype. 26814 26815RM References: 6.05 (5.2/2) 26816@end itemize 26817 26818@geindex AI-0058 (Ada 2012 feature) 26819 26820 26821@itemize * 26822 26823@item 26824@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 26825 26826The RM had some incorrect wording implying wrong treatment of abnormal 26827completion in an extended return. GNAT has always implemented the intended 26828correct semantics as described by this AI. 26829 26830RM References: 6.05 (22/2) 26831@end itemize 26832 26833@geindex AI-0050 (Ada 2012 feature) 26834 26835 26836@itemize * 26837 26838@item 26839@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 26840 26841The implementation permissions for raising @cite{Constraint_Error} early on a function call 26842when it was clear an exception would be raised were over-permissive and allowed 26843mishandling of discriminants in some cases. GNAT did 26844not take advantage of these incorrect permissions in any case. 26845 26846RM References: 6.05 (24/2) 26847@end itemize 26848 26849@geindex AI-0125 (Ada 2012 feature) 26850 26851 26852@itemize * 26853 26854@item 26855@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 26856 26857In Ada 2012, the declaration of a primitive operation of a type extension 26858or private extension can also override an inherited primitive that is not 26859visible at the point of this declaration. 26860 26861RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 26862@end itemize 26863 26864@geindex AI-0062 (Ada 2012 feature) 26865 26866 26867@itemize * 26868 26869@item 26870@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 26871 26872A full constant may have a null exclusion even if its associated deferred 26873constant does not. GNAT has always allowed this. 26874 26875RM References: 7.04 (6/2) 7.04 (7.1/2) 26876@end itemize 26877 26878@geindex AI-0178 (Ada 2012 feature) 26879 26880 26881@itemize * 26882 26883@item 26884@emph{AI-0178 Incomplete views are limited (0000-00-00)} 26885 26886This AI clarifies the role of incomplete views and plugs an omission in the 26887RM. GNAT always correctly restricted the use of incomplete views and types. 26888 26889RM References: 7.05 (3/2) 7.05 (6/2) 26890@end itemize 26891 26892@geindex AI-0087 (Ada 2012 feature) 26893 26894 26895@itemize * 26896 26897@item 26898@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 26899 26900The actual for a formal nonlimited derived type cannot be limited. In 26901particular, a formal derived type that extends a limited interface but which 26902is not explicitly limited cannot be instantiated with a limited type. 26903 26904RM References: 7.05 (5/2) 12.05.01 (5.1/2) 26905@end itemize 26906 26907@geindex AI-0099 (Ada 2012 feature) 26908 26909 26910@itemize * 26911 26912@item 26913@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 26914 26915This AI clarifies that 'needs finalization' is part of dynamic semantics, 26916and therefore depends on the run-time characteristics of an object (i.e. its 26917tag) and not on its nominal type. As the AI indicates: "we do not expect 26918this to affect any implementation'@w{'}. 26919 26920RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 26921@end itemize 26922 26923@geindex AI-0064 (Ada 2012 feature) 26924 26925 26926@itemize * 26927 26928@item 26929@emph{AI-0064 Redundant finalization rule (0000-00-00)} 26930 26931This is an editorial change only. The intended behavior is already checked 26932by an existing ACATS test, which GNAT has always executed correctly. 26933 26934RM References: 7.06.01 (17.1/1) 26935@end itemize 26936 26937@geindex AI-0026 (Ada 2012 feature) 26938 26939 26940@itemize * 26941 26942@item 26943@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 26944 26945Record representation clauses concerning Unchecked_Union types cannot mention 26946the discriminant of the type. The type of a component declared in the variant 26947part of an Unchecked_Union cannot be controlled, have controlled components, 26948nor have protected or task parts. If an Unchecked_Union type is declared 26949within the body of a generic unit or its descendants, then the type of a 26950component declared in the variant part cannot be a formal private type or a 26951formal private extension declared within the same generic unit. 26952 26953RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 26954@end itemize 26955 26956@geindex AI-0205 (Ada 2012 feature) 26957 26958 26959@itemize * 26960 26961@item 26962@emph{AI-0205 Extended return declares visible name (0000-00-00)} 26963 26964This AI corrects a simple omission in the RM. Return objects have always 26965been visible within an extended return statement. 26966 26967RM References: 8.03 (17) 26968@end itemize 26969 26970@geindex AI-0042 (Ada 2012 feature) 26971 26972 26973@itemize * 26974 26975@item 26976@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 26977 26978This AI fixes a wording gap in the RM. An operation of a synchronized 26979interface can be implemented by a protected or task entry, but the abstract 26980operation is not being overridden in the usual sense, and it must be stated 26981separately that this implementation is legal. This has always been the case 26982in GNAT. 26983 26984RM References: 9.01 (9.2/2) 9.04 (11.1/2) 26985@end itemize 26986 26987@geindex AI-0030 (Ada 2012 feature) 26988 26989 26990@itemize * 26991 26992@item 26993@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 26994 26995Requeue is permitted to a protected, synchronized or task interface primitive 26996providing it is known that the overriding operation is an entry. Otherwise 26997the requeue statement has the same effect as a procedure call. Use of pragma 26998@cite{Implemented} provides a way to impose a static requirement on the 26999overriding operation by adhering to one of the implementation kinds: entry, 27000protected procedure or any of the above. 27001 27002RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 270039.05.04 (6) 9.05.04 (7) 9.05.04 (12) 27004@end itemize 27005 27006@geindex AI-0201 (Ada 2012 feature) 27007 27008 27009@itemize * 27010 27011@item 27012@emph{AI-0201 Independence of atomic object components (2010-07-22)} 27013 27014If an Atomic object has a pragma @cite{Pack} or a @cite{Component_Size} 27015attribute, then individual components may not be addressable by independent 27016tasks. However, if the representation clause has no effect (is confirming), 27017then independence is not compromised. Furthermore, in GNAT, specification of 27018other appropriately addressable component sizes (e.g. 16 for 8-bit 27019characters) also preserves independence. GNAT now gives very clear warnings 27020both for the declaration of such a type, and for any assignment to its components. 27021 27022RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 27023@end itemize 27024 27025@geindex AI-0009 (Ada 2012 feature) 27026 27027 27028@itemize * 27029 27030@item 27031@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 27032 27033This AI introduces the new pragmas @cite{Independent} and 27034@cite{Independent_Components}, 27035which control guaranteeing independence of access to objects and components. 27036The AI also requires independence not unaffected by confirming rep clauses. 27037 27038RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 27039C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 27040@end itemize 27041 27042@geindex AI-0072 (Ada 2012 feature) 27043 27044 27045@itemize * 27046 27047@item 27048@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 27049 27050This AI clarifies that task signalling for reading @cite{'Terminated} only 27051occurs if the result is True. GNAT semantics has always been consistent with 27052this notion of task signalling. 27053 27054RM References: 9.10 (6.1/1) 27055@end itemize 27056 27057@geindex AI-0108 (Ada 2012 feature) 27058 27059 27060@itemize * 27061 27062@item 27063@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 27064 27065This AI confirms that an incomplete type from a limited view does not have 27066discriminants. This has always been the case in GNAT. 27067 27068RM References: 10.01.01 (12.3/2) 27069@end itemize 27070 27071@geindex AI-0129 (Ada 2012 feature) 27072 27073 27074@itemize * 27075 27076@item 27077@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 27078 27079This AI clarifies the description of limited views: a limited view of a 27080package includes only one view of a type that has an incomplete declaration 27081and a full declaration (there is no possible ambiguity in a client package). 27082This AI also fixes an omission: a nested package in the private part has no 27083limited view. GNAT always implemented this correctly. 27084 27085RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 27086@end itemize 27087 27088@geindex AI-0077 (Ada 2012 feature) 27089 27090 27091@itemize * 27092 27093@item 27094@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 27095 27096This AI clarifies that a declaration does not include a context clause, 27097and confirms that it is illegal to have a context in which both a limited 27098and a nonlimited view of a package are accessible. Such double visibility 27099was always rejected by GNAT. 27100 27101RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 27102@end itemize 27103 27104@geindex AI-0122 (Ada 2012 feature) 27105 27106 27107@itemize * 27108 27109@item 27110@emph{AI-0122 Private with and children of generics (0000-00-00)} 27111 27112This AI clarifies the visibility of private children of generic units within 27113instantiations of a parent. GNAT has always handled this correctly. 27114 27115RM References: 10.01.02 (12/2) 27116@end itemize 27117 27118@geindex AI-0040 (Ada 2012 feature) 27119 27120 27121@itemize * 27122 27123@item 27124@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 27125 27126This AI confirms that a limited with clause in a child unit cannot name 27127an ancestor of the unit. This has always been checked in GNAT. 27128 27129RM References: 10.01.02 (20/2) 27130@end itemize 27131 27132@geindex AI-0132 (Ada 2012 feature) 27133 27134 27135@itemize * 27136 27137@item 27138@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 27139 27140This AI fills a gap in the description of library unit pragmas. The pragma 27141clearly must apply to a library unit, even if it does not carry the name 27142of the enclosing unit. GNAT has always enforced the required check. 27143 27144RM References: 10.01.05 (7) 27145@end itemize 27146 27147@geindex AI-0034 (Ada 2012 feature) 27148 27149 27150@itemize * 27151 27152@item 27153@emph{AI-0034 Categorization of limited views (0000-00-00)} 27154 27155The RM makes certain limited with clauses illegal because of categorization 27156considerations, when the corresponding normal with would be legal. This is 27157not intended, and GNAT has always implemented the recommended behavior. 27158 27159RM References: 10.02.01 (11/1) 10.02.01 (17/2) 27160@end itemize 27161 27162@geindex AI-0035 (Ada 2012 feature) 27163 27164 27165@itemize * 27166 27167@item 27168@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 27169 27170This AI remedies some inconsistencies in the legality rules for Pure units. 27171Derived access types are legal in a pure unit (on the assumption that the 27172rule for a zero storage pool size has been enforced on the ancestor type). 27173The rules are enforced in generic instances and in subunits. GNAT has always 27174implemented the recommended behavior. 27175 27176RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 27177@end itemize 27178 27179@geindex AI-0219 (Ada 2012 feature) 27180 27181 27182@itemize * 27183 27184@item 27185@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 27186 27187This AI refines the rules for the cases with limited parameters which do not 27188allow the implementations to omit 'redundant'. GNAT now properly conforms 27189to the requirements of this binding interpretation. 27190 27191RM References: 10.02.01 (18/2) 27192@end itemize 27193 27194@geindex AI-0043 (Ada 2012 feature) 27195 27196 27197@itemize * 27198 27199@item 27200@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 27201 27202This AI covers various omissions in the RM regarding the raising of 27203exceptions. GNAT has always implemented the intended semantics. 27204 27205RM References: 11.04.01 (10.1/2) 11 (2) 27206@end itemize 27207 27208@geindex AI-0200 (Ada 2012 feature) 27209 27210 27211@itemize * 27212 27213@item 27214@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 27215 27216This AI plugs a gap in the RM which appeared to allow some obviously intended 27217illegal instantiations. GNAT has never allowed these instantiations. 27218 27219RM References: 12.07 (16) 27220@end itemize 27221 27222@geindex AI-0112 (Ada 2012 feature) 27223 27224 27225@itemize * 27226 27227@item 27228@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 27229 27230This AI concerns giving names to various representation aspects, but the 27231practical effect is simply to make the use of duplicate 27232@cite{Atomic[_Components]}, 27233@cite{Volatile[_Components]}, and 27234@cite{Independent[_Components]} pragmas illegal, and GNAT 27235now performs this required check. 27236 27237RM References: 13.01 (8) 27238@end itemize 27239 27240@geindex AI-0106 (Ada 2012 feature) 27241 27242 27243@itemize * 27244 27245@item 27246@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 27247 27248The RM appeared to allow representation pragmas on generic formal parameters, 27249but this was not intended, and GNAT has never permitted this usage. 27250 27251RM References: 13.01 (9.1/1) 27252@end itemize 27253 27254@geindex AI-0012 (Ada 2012 feature) 27255 27256 27257@itemize * 27258 27259@item 27260@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 27261 27262It is now illegal to give an inappropriate component size or a pragma 27263@cite{Pack} that attempts to change the component size in the case of atomic 27264or aliased components. Previously GNAT ignored such an attempt with a 27265warning. 27266 27267RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 27268@end itemize 27269 27270@geindex AI-0039 (Ada 2012 feature) 27271 27272 27273@itemize * 27274 27275@item 27276@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 27277 27278The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 27279for stream attributes, but these were never useful and are now illegal. GNAT 27280has always regarded such expressions as illegal. 27281 27282RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 27283@end itemize 27284 27285@geindex AI-0095 (Ada 2012 feature) 27286 27287 27288@itemize * 27289 27290@item 27291@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 27292 27293The prefix of @cite{'Address} cannot statically denote a subprogram with 27294convention @cite{Intrinsic}. The use of the @cite{Address} attribute raises 27295@cite{Program_Error} if the prefix denotes a subprogram with convention 27296@cite{Intrinsic}. 27297 27298RM References: 13.03 (11/1) 27299@end itemize 27300 27301@geindex AI-0116 (Ada 2012 feature) 27302 27303 27304@itemize * 27305 27306@item 27307@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 27308 27309This AI requires that the alignment of a class-wide object be no greater 27310than the alignment of any type in the class. GNAT has always followed this 27311recommendation. 27312 27313RM References: 13.03 (29) 13.11 (16) 27314@end itemize 27315 27316@geindex AI-0146 (Ada 2012 feature) 27317 27318 27319@itemize * 27320 27321@item 27322@emph{AI-0146 Type invariants (2009-09-21)} 27323 27324Type invariants may be specified for private types using the aspect notation. 27325Aspect @cite{Type_Invariant} may be specified for any private type, 27326@cite{Type_Invariant'Class} can 27327only be specified for tagged types, and is inherited by any descendent of the 27328tagged types. The invariant is a boolean expression that is tested for being 27329true in the following situations: conversions to the private type, object 27330declarations for the private type that are default initialized, and 27331[@strong{in}] @strong{out} 27332parameters and returned result on return from any primitive operation for 27333the type that is visible to a client. 27334GNAT defines the synonyms @cite{Invariant} for @cite{Type_Invariant} and 27335@cite{Invariant'Class} for @cite{Type_Invariant'Class}. 27336 27337RM References: 13.03.03 (00) 27338@end itemize 27339 27340@geindex AI-0078 (Ada 2012 feature) 27341 27342 27343@itemize * 27344 27345@item 27346@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 27347 27348In Ada 2012, compilers are required to support unchecked conversion where the 27349target alignment is a multiple of the source alignment. GNAT always supported 27350this case (and indeed all cases of differing alignments, doing copies where 27351required if the alignment was reduced). 27352 27353RM References: 13.09 (7) 27354@end itemize 27355 27356@geindex AI-0195 (Ada 2012 feature) 27357 27358 27359@itemize * 27360 27361@item 27362@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 27363 27364The handling of invalid values is now designated to be implementation 27365defined. This is a documentation change only, requiring Annex M in the GNAT 27366Reference Manual to document this handling. 27367In GNAT, checks for invalid values are made 27368only when necessary to avoid erroneous behavior. Operations like assignments 27369which cannot cause erroneous behavior ignore the possibility of invalid 27370values and do not do a check. The date given above applies only to the 27371documentation change, this behavior has always been implemented by GNAT. 27372 27373RM References: 13.09.01 (10) 27374@end itemize 27375 27376@geindex AI-0193 (Ada 2012 feature) 27377 27378 27379@itemize * 27380 27381@item 27382@emph{AI-0193 Alignment of allocators (2010-09-16)} 27383 27384This AI introduces a new attribute @cite{Max_Alignment_For_Allocation}, 27385analogous to @cite{Max_Size_In_Storage_Elements}, but for alignment instead 27386of size. 27387 27388RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2738913.11.01 (2) 13.11.01 (3) 27390@end itemize 27391 27392@geindex AI-0177 (Ada 2012 feature) 27393 27394 27395@itemize * 27396 27397@item 27398@emph{AI-0177 Parameterized expressions (2010-07-10)} 27399 27400The new Ada 2012 notion of parameterized expressions is implemented. The form 27401is: 27402 27403@example 27404function-specification is (expression) 27405@end example 27406 27407This is exactly equivalent to the 27408corresponding function body that returns the expression, but it can appear 27409in a package spec. Note that the expression must be parenthesized. 27410 27411RM References: 13.11.01 (3/2) 27412@end itemize 27413 27414@geindex AI-0033 (Ada 2012 feature) 27415 27416 27417@itemize * 27418 27419@item 27420@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 27421 27422Neither of these two pragmas may appear within a generic template, because 27423the generic might be instantiated at other than the library level. 27424 27425RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 27426@end itemize 27427 27428@geindex AI-0161 (Ada 2012 feature) 27429 27430 27431@itemize * 27432 27433@item 27434@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 27435 27436A new restriction @cite{No_Default_Stream_Attributes} prevents the use of any 27437of the default stream attributes for elementary types. If this restriction is 27438in force, then it is necessary to provide explicit subprograms for any 27439stream attributes used. 27440 27441RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 27442@end itemize 27443 27444@geindex AI-0194 (Ada 2012 feature) 27445 27446 27447@itemize * 27448 27449@item 27450@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 27451 27452The @cite{Stream_Size} attribute returns the default number of bits in the 27453stream representation of the given type. 27454This value is not affected by the presence 27455of stream subprogram attributes for the type. GNAT has always implemented 27456this interpretation. 27457 27458RM References: 13.13.02 (1.2/2) 27459@end itemize 27460 27461@geindex AI-0109 (Ada 2012 feature) 27462 27463 27464@itemize * 27465 27466@item 27467@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 27468 27469This AI is an editorial change only. It removes the need for a tag check 27470that can never fail. 27471 27472RM References: 13.13.02 (34/2) 27473@end itemize 27474 27475@geindex AI-0007 (Ada 2012 feature) 27476 27477 27478@itemize * 27479 27480@item 27481@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 27482 27483The RM as written appeared to limit the possibilities of declaring read 27484attribute procedures for private scalar types. This limitation was not 27485intended, and has never been enforced by GNAT. 27486 27487RM References: 13.13.02 (50/2) 13.13.02 (51/2) 27488@end itemize 27489 27490@geindex AI-0065 (Ada 2012 feature) 27491 27492 27493@itemize * 27494 27495@item 27496@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 27497 27498This AI clarifies the fact that all remote access types support external 27499streaming. This fixes an obvious oversight in the definition of the 27500language, and GNAT always implemented the intended correct rules. 27501 27502RM References: 13.13.02 (52/2) 27503@end itemize 27504 27505@geindex AI-0019 (Ada 2012 feature) 27506 27507 27508@itemize * 27509 27510@item 27511@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 27512 27513The RM suggests that primitive subprograms of a specific tagged type are 27514frozen when the tagged type is frozen. This would be an incompatible change 27515and is not intended. GNAT has never attempted this kind of freezing and its 27516behavior is consistent with the recommendation of this AI. 27517 27518RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 27519@end itemize 27520 27521@geindex AI-0017 (Ada 2012 feature) 27522 27523 27524@itemize * 27525 27526@item 27527@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 27528 27529So-called 'Taft-amendment types' (i.e., types that are completed in package 27530bodies) are not frozen by the occurrence of bodies in the 27531enclosing declarative part. GNAT always implemented this properly. 27532 27533RM References: 13.14 (3/1) 27534@end itemize 27535 27536@geindex AI-0060 (Ada 2012 feature) 27537 27538 27539@itemize * 27540 27541@item 27542@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 27543 27544This AI extends the definition of remote access types to include access 27545to limited, synchronized, protected or task class-wide interface types. 27546GNAT already implemented this extension. 27547 27548RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 27549@end itemize 27550 27551@geindex AI-0114 (Ada 2012 feature) 27552 27553 27554@itemize * 27555 27556@item 27557@emph{AI-0114 Classification of letters (0000-00-00)} 27558 27559The code points 170 (@cite{FEMININE ORDINAL INDICATOR}), 27560181 (@cite{MICRO SIGN}), and 27561186 (@cite{MASCULINE ORDINAL INDICATOR}) are technically considered 27562lower case letters by Unicode. 27563However, they are not allowed in identifiers, and they 27564return @cite{False} to @cite{Ada.Characters.Handling.Is_Letter/Is_Lower}. 27565This behavior is consistent with that defined in Ada 95. 27566 27567RM References: A.03.02 (59) A.04.06 (7) 27568@end itemize 27569 27570@geindex AI-0185 (Ada 2012 feature) 27571 27572 27573@itemize * 27574 27575@item 27576@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 27577 27578Two new packages @cite{Ada.Wide_[Wide_]Characters.Handling} provide 27579classification functions for @cite{Wide_Character} and 27580@cite{Wide_Wide_Character}, as well as providing 27581case folding routines for @cite{Wide_[Wide_]Character} and 27582@cite{Wide_[Wide_]String}. 27583 27584RM References: A.03.05 (0) A.03.06 (0) 27585@end itemize 27586 27587@geindex AI-0031 (Ada 2012 feature) 27588 27589 27590@itemize * 27591 27592@item 27593@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 27594 27595A new version of @cite{Find_Token} is added to all relevant string packages, 27596with an extra parameter @cite{From}. Instead of starting at the first 27597character of the string, the search for a matching Token starts at the 27598character indexed by the value of @cite{From}. 27599These procedures are available in all versions of Ada 27600but if used in versions earlier than Ada 2012 they will generate a warning 27601that an Ada 2012 subprogram is being used. 27602 27603RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 27604A.04.05 (46) 27605@end itemize 27606 27607@geindex AI-0056 (Ada 2012 feature) 27608 27609 27610@itemize * 27611 27612@item 27613@emph{AI-0056 Index on null string returns zero (0000-00-00)} 27614 27615The wording in the Ada 2005 RM implied an incompatible handling of the 27616@cite{Index} functions, resulting in raising an exception instead of 27617returning zero in some situations. 27618This was not intended and has been corrected. 27619GNAT always returned zero, and is thus consistent with this AI. 27620 27621RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 27622@end itemize 27623 27624@geindex AI-0137 (Ada 2012 feature) 27625 27626 27627@itemize * 27628 27629@item 27630@emph{AI-0137 String encoding package (2010-03-25)} 27631 27632The packages @cite{Ada.Strings.UTF_Encoding}, together with its child 27633packages, @cite{Conversions}, @cite{Strings}, @cite{Wide_Strings}, 27634and @cite{Wide_Wide_Strings} have been 27635implemented. These packages (whose documentation can be found in the spec 27636files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 27637@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 27638@cite{String}, @cite{Wide_String}, and @cite{Wide_Wide_String} 27639values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 27640UTF-16), as well as conversions between the different UTF encodings. With 27641the exception of @cite{Wide_Wide_Strings}, these packages are available in 27642Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 27643The @cite{Wide_Wide_Strings package} 27644is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 27645mode since it uses @cite{Wide_Wide_Character}). 27646 27647RM References: A.04.11 27648@end itemize 27649 27650@geindex AI-0038 (Ada 2012 feature) 27651 27652 27653@itemize * 27654 27655@item 27656@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 27657 27658These are minor errors in the description on three points. The intent on 27659all these points has always been clear, and GNAT has always implemented the 27660correct intended semantics. 27661 27662RM 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) 27663@end itemize 27664 27665@geindex AI-0044 (Ada 2012 feature) 27666 27667 27668@itemize * 27669 27670@item 27671@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 27672 27673This AI places restrictions on allowed instantiations of generic containers. 27674These restrictions are not checked by the compiler, so there is nothing to 27675change in the implementation. This affects only the RM documentation. 27676 27677RM 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) 27678@end itemize 27679 27680@geindex AI-0127 (Ada 2012 feature) 27681 27682 27683@itemize * 27684 27685@item 27686@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 27687 27688This package provides an interface for identifying the current locale. 27689 27690RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 27691A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 27692@end itemize 27693 27694@geindex AI-0002 (Ada 2012 feature) 27695 27696 27697@itemize * 27698 27699@item 27700@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 27701 27702The compiler is not required to support exporting an Ada subprogram with 27703convention C if there are parameters or a return type of an unconstrained 27704array type (such as @cite{String}). GNAT allows such declarations but 27705generates warnings. It is possible, but complicated, to write the 27706corresponding C code and certainly such code would be specific to GNAT and 27707non-portable. 27708 27709RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 27710@end itemize 27711 27712@geindex AI05-0216 (Ada 2012 feature) 27713 27714 27715@itemize * 27716 27717@item 27718@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 27719 27720It is clearly the intention that @cite{No_Task_Hierarchy} is intended to 27721forbid tasks declared locally within subprograms, or functions returning task 27722objects, and that is the implementation that GNAT has always provided. 27723However the language in the RM was not sufficiently clear on this point. 27724Thus this is a documentation change in the RM only. 27725 27726RM References: D.07 (3/3) 27727@end itemize 27728 27729@geindex AI-0211 (Ada 2012 feature) 27730 27731 27732@itemize * 27733 27734@item 27735@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 27736 27737The restriction @cite{No_Relative_Delays} forbids any calls to the subprogram 27738@cite{Ada.Real_Time.Timing_Events.Set_Handler}. 27739 27740RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 27741@end itemize 27742 27743@geindex AI-0190 (Ada 2012 feature) 27744 27745 27746@itemize * 27747 27748@item 27749@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 27750 27751This AI introduces a new pragma @cite{Default_Storage_Pool}, which can be 27752used to control storage pools globally. 27753In particular, you can force every access 27754type that is used for allocation (@strong{new}) to have an explicit storage pool, 27755or you can declare a pool globally to be used for all access types that lack 27756an explicit one. 27757 27758RM References: D.07 (8) 27759@end itemize 27760 27761@geindex AI-0189 (Ada 2012 feature) 27762 27763 27764@itemize * 27765 27766@item 27767@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 27768 27769This AI introduces a new restriction @cite{No_Allocators_After_Elaboration}, 27770which says that no dynamic allocation will occur once elaboration is 27771completed. 27772In general this requires a run-time check, which is not required, and which 27773GNAT does not attempt. But the static cases of allocators in a task body or 27774in the body of the main program are detected and flagged at compile or bind 27775time. 27776 27777RM References: D.07 (19.1/2) H.04 (23.3/2) 27778@end itemize 27779 27780@geindex AI-0171 (Ada 2012 feature) 27781 27782 27783@itemize * 27784 27785@item 27786@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 27787 27788A new package @cite{System.Multiprocessors} is added, together with the 27789definition of pragma @cite{CPU} for controlling task affinity. A new no 27790dependence restriction, on @cite{System.Multiprocessors.Dispatching_Domains}, 27791is added to the Ravenscar profile. 27792 27793RM References: D.13.01 (4/2) D.16 27794@end itemize 27795 27796@geindex AI-0210 (Ada 2012 feature) 27797 27798 27799@itemize * 27800 27801@item 27802@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 27803 27804This is a documentation only issue regarding wording of metric requirements, 27805that does not affect the implementation of the compiler. 27806 27807RM References: D.15 (24/2) 27808@end itemize 27809 27810@geindex AI-0206 (Ada 2012 feature) 27811 27812 27813@itemize * 27814 27815@item 27816@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 27817 27818Remote types packages are now allowed to depend on preelaborated packages. 27819This was formerly considered illegal. 27820 27821RM References: E.02.02 (6) 27822@end itemize 27823 27824@geindex AI-0152 (Ada 2012 feature) 27825 27826 27827@itemize * 27828 27829@item 27830@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 27831 27832Restriction @cite{No_Anonymous_Allocators} prevents the use of allocators 27833where the type of the returned value is an anonymous access type. 27834 27835RM References: H.04 (8/1) 27836@end itemize 27837 27838@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top 27839@anchor{gnat_rm/obsolescent_features id1}@anchor{3dc}@anchor{gnat_rm/obsolescent_features doc}@anchor{3dd}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15} 27840@chapter Obsolescent Features 27841 27842 27843This chapter describes features that are provided by GNAT, but are 27844considered obsolescent since there are preferred ways of achieving 27845the same effect. These features are provided solely for historical 27846compatibility purposes. 27847 27848@menu 27849* pragma No_Run_Time:: 27850* pragma Ravenscar:: 27851* pragma Restricted_Run_Time:: 27852* pragma Task_Info:: 27853* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 27854 27855@end menu 27856 27857@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 27858@anchor{gnat_rm/obsolescent_features id2}@anchor{3de}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{3df} 27859@section pragma No_Run_Time 27860 27861 27862The pragma @cite{No_Run_Time} is used to achieve an affect similar 27863to the use of the "Zero Foot Print" configurable run time, but without 27864requiring a specially configured run time. The result of using this 27865pragma, which must be used for all units in a partition, is to restrict 27866the use of any language features requiring run-time support code. The 27867preferred usage is to use an appropriately configured run-time that 27868includes just those features that are to be made accessible. 27869 27870@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 27871@anchor{gnat_rm/obsolescent_features id3}@anchor{3e0}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{3e1} 27872@section pragma Ravenscar 27873 27874 27875The pragma @cite{Ravenscar} has exactly the same effect as pragma 27876@cite{Profile (Ravenscar)}. The latter usage is preferred since it 27877is part of the new Ada 2005 standard. 27878 27879@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 27880@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{3e2}@anchor{gnat_rm/obsolescent_features id4}@anchor{3e3} 27881@section pragma Restricted_Run_Time 27882 27883 27884The pragma @cite{Restricted_Run_Time} has exactly the same effect as 27885pragma @cite{Profile (Restricted)}. The latter usage is 27886preferred since the Ada 2005 pragma @cite{Profile} is intended for 27887this kind of implementation dependent addition. 27888 27889@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 27890@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{3e4}@anchor{gnat_rm/obsolescent_features id5}@anchor{3e5} 27891@section pragma Task_Info 27892 27893 27894The functionality provided by pragma @cite{Task_Info} is now part of the 27895Ada language. The @cite{CPU} aspect and the package 27896@cite{System.Multiprocessors} offer a less system-dependent way to specify 27897task affinity or to query the number of processsors. 27898 27899Syntax 27900 27901@example 27902pragma Task_Info (EXPRESSION); 27903@end example 27904 27905This pragma appears within a task definition (like pragma 27906@cite{Priority}) and applies to the task in which it appears. The 27907argument must be of type @cite{System.Task_Info.Task_Info_Type}. 27908The @cite{Task_Info} pragma provides system dependent control over 27909aspects of tasking implementation, for example, the ability to map 27910tasks to specific processors. For details on the facilities available 27911for the version of GNAT that you are using, see the documentation 27912in the spec of package System.Task_Info in the runtime 27913library. 27914 27915@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 27916@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{3e6}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{3e7} 27917@section package System.Task_Info (@code{s-tasinf.ads}) 27918 27919 27920This package provides target dependent functionality that is used 27921to support the @cite{Task_Info} pragma. The predefined Ada package 27922@cite{System.Multiprocessors} and the @cite{CPU} aspect now provide a 27923standard replacement for GNAT's @cite{Task_Info} functionality. 27924 27925@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 27926@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{3e8}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{3e9} 27927@chapter Compatibility and Porting Guide 27928 27929 27930This chapter presents some guidelines for developing portable Ada code, 27931describes the compatibility issues that may arise between 27932GNAT and other Ada compilation systems (including those for Ada 83), 27933and shows how GNAT can expedite porting 27934applications developed in other Ada environments. 27935 27936@menu 27937* Writing Portable Fixed-Point Declarations:: 27938* Compatibility with Ada 83:: 27939* Compatibility between Ada 95 and Ada 2005:: 27940* Implementation-dependent characteristics:: 27941* Compatibility with Other Ada Systems:: 27942* Representation Clauses:: 27943* Compatibility with HP Ada 83:: 27944 27945@end menu 27946 27947@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 27948@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{3ea}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{3eb} 27949@section Writing Portable Fixed-Point Declarations 27950 27951 27952The Ada Reference Manual gives an implementation freedom to choose bounds 27953that are narrower by @cite{Small} from the given bounds. 27954For example, if we write 27955 27956@example 27957type F1 is delta 1.0 range -128.0 .. +128.0; 27958@end example 27959 27960then the implementation is allowed to choose -128.0 .. +127.0 if it 27961likes, but is not required to do so. 27962 27963This leads to possible portability problems, so let's have a closer 27964look at this, and figure out how to avoid these problems. 27965 27966First, why does this freedom exist, and why would an implementation 27967take advantage of it? To answer this, take a closer look at the type 27968declaration for @cite{F1} above. If the compiler uses the given bounds, 27969it would need 9 bits to hold the largest positive value (and typically 27970that means 16 bits on all machines). But if the implementation chooses 27971the +127.0 bound then it can fit values of the type in 8 bits. 27972 27973Why not make the user write +127.0 if that's what is wanted? 27974The rationale is that if you are thinking of fixed point 27975as a kind of 'poor man's floating-point', then you don't want 27976to be thinking about the scaled integers that are used in its 27977representation. Let's take another example: 27978 27979@example 27980type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 27981@end example 27982 27983Looking at this declaration, it seems casually as though 27984it should fit in 16 bits, but again that extra positive value 27985+1.0 has the scaled integer equivalent of 2**15 which is one too 27986big for signed 16 bits. The implementation can treat this as: 27987 27988@example 27989type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 27990@end example 27991 27992and the Ada language design team felt that this was too annoying 27993to require. We don't need to debate this decision at this point, 27994since it is well established (the rule about narrowing the ranges 27995dates to Ada 83). 27996 27997But the important point is that an implementation is not required 27998to do this narrowing, so we have a potential portability problem. 27999We could imagine three types of implementation: 28000 28001 28002@enumerate a 28003 28004@item 28005those that narrow the range automatically if they can figure 28006out that the narrower range will allow storage in a smaller machine unit, 28007 28008@item 28009those that will narrow only if forced to by a @cite{'Size} clause, and 28010 28011@item 28012those that will never narrow. 28013@end enumerate 28014 28015Now if we are language theoreticians, we can imagine a fourth 28016approach: to narrow all the time, e.g. to treat 28017 28018@example 28019type F3 is delta 1.0 range -10.0 .. +23.0; 28020@end example 28021 28022as though it had been written: 28023 28024@example 28025type F3 is delta 1.0 range -9.0 .. +22.0; 28026@end example 28027 28028But although technically allowed, such a behavior would be hostile and silly, 28029and no real compiler would do this. All real compilers will fall into one of 28030the categories (a), (b) or (c) above. 28031 28032So, how do you get the compiler to do what you want? The answer is give the 28033actual bounds you want, and then use a @cite{'Small} clause and a 28034@cite{'Size} clause to absolutely pin down what the compiler does. 28035E.g., for @cite{F2} above, we will write: 28036 28037@example 28038My_Small : constant := 2.0**(-15); 28039My_First : constant := -1.0; 28040My_Last : constant := +1.0 - My_Small; 28041 28042type F2 is delta My_Small range My_First .. My_Last; 28043@end example 28044 28045and then add 28046 28047@example 28048for F2'Small use my_Small; 28049for F2'Size use 16; 28050@end example 28051 28052In practice all compilers will do the same thing here and will give you 28053what you want, so the above declarations are fully portable. If you really 28054want to play language lawyer and guard against ludicrous behavior by the 28055compiler you could add 28056 28057@example 28058Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 28059Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 28060@end example 28061 28062One or other or both are allowed to be illegal if the compiler is 28063behaving in a silly manner, but at least the silly compiler will not 28064get away with silently messing with your (very clear) intentions. 28065 28066If you follow this scheme you will be guaranteed that your fixed-point 28067types will be portable. 28068 28069@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 28070@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{3ec}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{3ed} 28071@section Compatibility with Ada 83 28072 28073 28074@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 28075 28076Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 28077are highly upwards compatible with Ada 83. In 28078particular, the design intention was that the difficulties associated 28079with moving from Ada 83 to later versions of the standard should be no greater 28080than those that occur when moving from one Ada 83 system to another. 28081 28082However, there are a number of points at which there are minor 28083incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 28084full details of these issues as they relate to Ada 95, 28085and should be consulted for a complete treatment. 28086In practice the 28087following subsections treat the most likely issues to be encountered. 28088 28089@menu 28090* Legal Ada 83 programs that are illegal in Ada 95:: 28091* More deterministic semantics:: 28092* Changed semantics:: 28093* Other language compatibility issues:: 28094 28095@end menu 28096 28097@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 28098@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{3ee}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{3ef} 28099@subsection Legal Ada 83 programs that are illegal in Ada 95 28100 28101 28102Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 28103Ada 95 and later versions of the standard: 28104 28105 28106@itemize * 28107 28108@item 28109@emph{Character literals} 28110 28111Some uses of character literals are ambiguous. Since Ada 95 has introduced 28112@cite{Wide_Character} as a new predefined character type, some uses of 28113character literals that were legal in Ada 83 are illegal in Ada 95. 28114For example: 28115 28116@example 28117for Char in 'A' .. 'Z' loop ... end loop; 28118@end example 28119 28120The problem is that 'A' and 'Z' could be from either 28121@cite{Character} or @cite{Wide_Character}. The simplest correction 28122is to make the type explicit; e.g.: 28123 28124@example 28125for Char in Character range 'A' .. 'Z' loop ... end loop; 28126@end example 28127 28128@item 28129@emph{New reserved words} 28130 28131The identifiers @cite{abstract}, @cite{aliased}, @cite{protected}, 28132@cite{requeue}, @cite{tagged}, and @cite{until} are reserved in Ada 95. 28133Existing Ada 83 code using any of these identifiers must be edited to 28134use some alternative name. 28135 28136@item 28137@emph{Freezing rules} 28138 28139The rules in Ada 95 are slightly different with regard to the point at 28140which entities are frozen, and representation pragmas and clauses are 28141not permitted past the freeze point. This shows up most typically in 28142the form of an error message complaining that a representation item 28143appears too late, and the appropriate corrective action is to move 28144the item nearer to the declaration of the entity to which it refers. 28145 28146A particular case is that representation pragmas 28147cannot be applied to a subprogram body. If necessary, a separate subprogram 28148declaration must be introduced to which the pragma can be applied. 28149 28150@item 28151@emph{Optional bodies for library packages} 28152 28153In Ada 83, a package that did not require a package body was nevertheless 28154allowed to have one. This lead to certain surprises in compiling large 28155systems (situations in which the body could be unexpectedly ignored by the 28156binder). In Ada 95, if a package does not require a body then it is not 28157permitted to have a body. To fix this problem, simply remove a redundant 28158body if it is empty, or, if it is non-empty, introduce a dummy declaration 28159into the spec that makes the body required. One approach is to add a private 28160part to the package declaration (if necessary), and define a parameterless 28161procedure called @cite{Requires_Body}, which must then be given a dummy 28162procedure body in the package body, which then becomes required. 28163Another approach (assuming that this does not introduce elaboration 28164circularities) is to add an @cite{Elaborate_Body} pragma to the package spec, 28165since one effect of this pragma is to require the presence of a package body. 28166 28167@item 28168@emph{Numeric_Error is the same exception as Constraint_Error} 28169 28170In Ada 95, the exception @cite{Numeric_Error} is a renaming of @cite{Constraint_Error}. 28171This means that it is illegal to have separate exception handlers for 28172the two exceptions. The fix is simply to remove the handler for the 28173@cite{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 28174@cite{Constraint_Error} in place of @cite{Numeric_Error} in all cases). 28175 28176@item 28177@emph{Indefinite subtypes in generics} 28178 28179In Ada 83, it was permissible to pass an indefinite type (e.g, @cite{String}) 28180as the actual for a generic formal private type, but then the instantiation 28181would be illegal if there were any instances of declarations of variables 28182of this type in the generic body. In Ada 95, to avoid this clear violation 28183of the methodological principle known as the 'contract model', 28184the generic declaration explicitly indicates whether 28185or not such instantiations are permitted. If a generic formal parameter 28186has explicit unknown discriminants, indicated by using @cite{(<>)} after the 28187subtype name, then it can be instantiated with indefinite types, but no 28188stand-alone variables can be declared of this type. Any attempt to declare 28189such a variable will result in an illegality at the time the generic is 28190declared. If the @cite{(<>)} notation is not used, then it is illegal 28191to instantiate the generic with an indefinite type. 28192This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 28193It will show up as a compile time error, and 28194the fix is usually simply to add the @cite{(<>)} to the generic declaration. 28195@end itemize 28196 28197@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 28198@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{3f0}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{3f1} 28199@subsection More deterministic semantics 28200 28201 28202 28203@itemize * 28204 28205@item 28206@emph{Conversions} 28207 28208Conversions from real types to integer types round away from 0. In Ada 83 28209the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 28210implementation freedom was intended to support unbiased rounding in 28211statistical applications, but in practice it interfered with portability. 28212In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 28213is required. Numeric code may be affected by this change in semantics. 28214Note, though, that this issue is no worse than already existed in Ada 83 28215when porting code from one vendor to another. 28216 28217@item 28218@emph{Tasking} 28219 28220The Real-Time Annex introduces a set of policies that define the behavior of 28221features that were implementation dependent in Ada 83, such as the order in 28222which open select branches are executed. 28223@end itemize 28224 28225@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 28226@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{3f2}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{3f3} 28227@subsection Changed semantics 28228 28229 28230The worst kind of incompatibility is one where a program that is legal in 28231Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 28232possible in Ada 83. Fortunately this is extremely rare, but the one 28233situation that you should be alert to is the change in the predefined type 28234@cite{Character} from 7-bit ASCII to 8-bit Latin-1. 28235 28236@quotation 28237 28238@geindex Latin-1 28239@end quotation 28240 28241 28242@itemize * 28243 28244@item 28245@emph{Range of type `Character`} 28246 28247The range of @cite{Standard.Character} is now the full 256 characters 28248of Latin-1, whereas in most Ada 83 implementations it was restricted 28249to 128 characters. Although some of the effects of 28250this change will be manifest in compile-time rejection of legal 28251Ada 83 programs it is possible for a working Ada 83 program to have 28252a different effect in Ada 95, one that was not permitted in Ada 83. 28253As an example, the expression 28254@cite{Character'Pos(Character'Last)} returned @cite{127} in Ada 83 and now 28255delivers @cite{255} as its value. 28256In general, you should look at the logic of any 28257character-processing Ada 83 program and see whether it needs to be adapted 28258to work correctly with Latin-1. Note that the predefined Ada 95 API has a 28259character handling package that may be relevant if code needs to be adapted 28260to account for the additional Latin-1 elements. 28261The desirable fix is to 28262modify the program to accommodate the full character set, but in some cases 28263it may be convenient to define a subtype or derived type of Character that 28264covers only the restricted range. 28265@end itemize 28266 28267@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 28268@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{3f4}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{3f5} 28269@subsection Other language compatibility issues 28270 28271 28272 28273@itemize * 28274 28275@item 28276@emph{-gnat83} switch 28277 28278All implementations of GNAT provide a switch that causes GNAT to operate 28279in Ada 83 mode. In this mode, some but not all compatibility problems 28280of the type described above are handled automatically. For example, the 28281new reserved words introduced in Ada 95 and Ada 2005 are treated simply 28282as identifiers as in Ada 83. However, 28283in practice, it is usually advisable to make the necessary modifications 28284to the program to remove the need for using this switch. 28285See the @cite{Compiling Different Versions of Ada} section in 28286the @cite{GNAT User's Guide}. 28287 28288@item 28289Support for removed Ada 83 pragmas and attributes 28290 28291A number of pragmas and attributes from Ada 83 were removed from Ada 95, 28292generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 28293compilers are allowed, but not required, to implement these missing 28294elements. In contrast with some other compilers, GNAT implements all 28295such pragmas and attributes, eliminating this compatibility concern. These 28296include @cite{pragma Interface} and the floating point type attributes 28297(@cite{Emax}, @cite{Mantissa}, etc.), among other items. 28298@end itemize 28299 28300@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 28301@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{3f6}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{3f7} 28302@section Compatibility between Ada 95 and Ada 2005 28303 28304 28305@geindex Compatibility between Ada 95 and Ada 2005 28306 28307Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 28308a number of incompatibilities. Several are enumerated below; 28309for a complete description please see the 28310@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 28311@cite{Rationale for Ada 2005}. 28312 28313 28314@itemize * 28315 28316@item 28317@emph{New reserved words.} 28318 28319The words @cite{interface}, @cite{overriding} and @cite{synchronized} are 28320reserved in Ada 2005. 28321A pre-Ada 2005 program that uses any of these as an identifier will be 28322illegal. 28323 28324@item 28325@emph{New declarations in predefined packages.} 28326 28327A number of packages in the predefined environment contain new declarations: 28328@cite{Ada.Exceptions}, @cite{Ada.Real_Time}, @cite{Ada.Strings}, 28329@cite{Ada.Strings.Fixed}, @cite{Ada.Strings.Bounded}, 28330@cite{Ada.Strings.Unbounded}, @cite{Ada.Strings.Wide_Fixed}, 28331@cite{Ada.Strings.Wide_Bounded}, @cite{Ada.Strings.Wide_Unbounded}, 28332@cite{Ada.Tags}, @cite{Ada.Text_IO}, and @cite{Interfaces.C}. 28333If an Ada 95 program does a @cite{with} and @cite{use} of any of these 28334packages, the new declarations may cause name clashes. 28335 28336@item 28337@emph{Access parameters.} 28338 28339A nondispatching subprogram with an access parameter cannot be renamed 28340as a dispatching operation. This was permitted in Ada 95. 28341 28342@item 28343@emph{Access types, discriminants, and constraints.} 28344 28345Rule changes in this area have led to some incompatibilities; for example, 28346constrained subtypes of some access types are not permitted in Ada 2005. 28347 28348@item 28349@emph{Aggregates for limited types.} 28350 28351The allowance of aggregates for limited types in Ada 2005 raises the 28352possibility of ambiguities in legal Ada 95 programs, since additional types 28353now need to be considered in expression resolution. 28354 28355@item 28356@emph{Fixed-point multiplication and division.} 28357 28358Certain expressions involving '*' or '/' for a fixed-point type, which 28359were legal in Ada 95 and invoked the predefined versions of these operations, 28360are now ambiguous. 28361The ambiguity may be resolved either by applying a type conversion to the 28362expression, or by explicitly invoking the operation from package 28363@cite{Standard}. 28364 28365@item 28366@emph{Return-by-reference types.} 28367 28368The Ada 95 return-by-reference mechanism has been removed. Instead, the user 28369can declare a function returning a value from an anonymous access type. 28370@end itemize 28371 28372@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 28373@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{3f8}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{3f9} 28374@section Implementation-dependent characteristics 28375 28376 28377Although the Ada language defines the semantics of each construct as 28378precisely as practical, in some situations (for example for reasons of 28379efficiency, or where the effect is heavily dependent on the host or target 28380platform) the implementation is allowed some freedom. In porting Ada 83 28381code to GNAT, you need to be aware of whether / how the existing code 28382exercised such implementation dependencies. Such characteristics fall into 28383several categories, and GNAT offers specific support in assisting the 28384transition from certain Ada 83 compilers. 28385 28386@menu 28387* Implementation-defined pragmas:: 28388* Implementation-defined attributes:: 28389* Libraries:: 28390* Elaboration order:: 28391* Target-specific aspects:: 28392 28393@end menu 28394 28395@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 28396@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{3fa}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{3fb} 28397@subsection Implementation-defined pragmas 28398 28399 28400Ada compilers are allowed to supplement the language-defined pragmas, and 28401these are a potential source of non-portability. All GNAT-defined pragmas 28402are described in the @cite{Implementation Defined Pragmas} chapter of the 28403@cite{GNAT Reference Manual}, and these include several that are specifically 28404intended to correspond to other vendors' Ada 83 pragmas. 28405For migrating from VADS, the pragma @cite{Use_VADS_Size} may be useful. 28406For compatibility with HP Ada 83, GNAT supplies the pragmas 28407@cite{Extend_System}, @cite{Ident}, @cite{Inline_Generic}, 28408@cite{Interface_Name}, @cite{Passive}, @cite{Suppress_All}, 28409and @cite{Volatile}. 28410Other relevant pragmas include @cite{External} and @cite{Link_With}. 28411Some vendor-specific 28412Ada 83 pragmas (@cite{Share_Generic}, @cite{Subtitle}, and @cite{Title}) are 28413recognized, thus 28414avoiding compiler rejection of units that contain such pragmas; they are not 28415relevant in a GNAT context and hence are not otherwise implemented. 28416 28417@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 28418@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{3fc}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{3fd} 28419@subsection Implementation-defined attributes 28420 28421 28422Analogous to pragmas, the set of attributes may be extended by an 28423implementation. All GNAT-defined attributes are described in 28424@cite{Implementation Defined Attributes} section of the 28425@cite{GNAT Reference Manual}, and these include several that are specifically intended 28426to correspond to other vendors' Ada 83 attributes. For migrating from VADS, 28427the attribute @cite{VADS_Size} may be useful. For compatibility with HP 28428Ada 83, GNAT supplies the attributes @cite{Bit}, @cite{Machine_Size} and 28429@cite{Type_Class}. 28430 28431@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 28432@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{3fe}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{3ff} 28433@subsection Libraries 28434 28435 28436Vendors may supply libraries to supplement the standard Ada API. If Ada 83 28437code uses vendor-specific libraries then there are several ways to manage 28438this in Ada 95 and later versions of the standard: 28439 28440 28441@itemize * 28442 28443@item 28444If the source code for the libraries (specs and bodies) are 28445available, then the libraries can be migrated in the same way as the 28446application. 28447 28448@item 28449If the source code for the specs but not the bodies are 28450available, then you can reimplement the bodies. 28451 28452@item 28453Some features introduced by Ada 95 obviate the need for library support. For 28454example most Ada 83 vendors supplied a package for unsigned integers. The 28455Ada 95 modular type feature is the preferred way to handle this need, so 28456instead of migrating or reimplementing the unsigned integer package it may 28457be preferable to retrofit the application using modular types. 28458@end itemize 28459 28460@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 28461@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{400}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{401} 28462@subsection Elaboration order 28463 28464 28465The implementation can choose any elaboration order consistent with the unit 28466dependency relationship. This freedom means that some orders can result in 28467Program_Error being raised due to an 'Access Before Elaboration': an attempt 28468to invoke a subprogram before its body has been elaborated, or to instantiate 28469a generic before the generic body has been elaborated. By default GNAT 28470attempts to choose a safe order (one that will not encounter access before 28471elaboration problems) by implicitly inserting @cite{Elaborate} or 28472@cite{Elaborate_All} pragmas where 28473needed. However, this can lead to the creation of elaboration circularities 28474and a resulting rejection of the program by gnatbind. This issue is 28475thoroughly described in the @cite{Elaboration Order Handling in GNAT} appendix 28476in the @cite{GNAT User's Guide}. 28477In brief, there are several 28478ways to deal with this situation: 28479 28480 28481@itemize * 28482 28483@item 28484Modify the program to eliminate the circularities, e.g., by moving 28485elaboration-time code into explicitly-invoked procedures 28486 28487@item 28488Constrain the elaboration order by including explicit @cite{Elaborate_Body} or 28489@cite{Elaborate} pragmas, and then inhibit the generation of implicit 28490@cite{Elaborate_All} 28491pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 28492(by selectively suppressing elaboration checks via pragma 28493@cite{Suppress(Elaboration_Check)} when it is safe to do so). 28494@end itemize 28495 28496@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 28497@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{402}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{403} 28498@subsection Target-specific aspects 28499 28500 28501Low-level applications need to deal with machine addresses, data 28502representations, interfacing with assembler code, and similar issues. If 28503such an Ada 83 application is being ported to different target hardware (for 28504example where the byte endianness has changed) then you will need to 28505carefully examine the program logic; the porting effort will heavily depend 28506on the robustness of the original design. Moreover, Ada 95 (and thus 28507Ada 2005 and Ada 2012) are sometimes 28508incompatible with typical Ada 83 compiler practices regarding implicit 28509packing, the meaning of the Size attribute, and the size of access values. 28510GNAT's approach to these issues is described in @ref{404,,Representation Clauses}. 28511 28512@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 28513@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{405}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{406} 28514@section Compatibility with Other Ada Systems 28515 28516 28517If programs avoid the use of implementation dependent and 28518implementation defined features, as documented in the 28519@cite{Ada Reference Manual}, there should be a high degree of portability between 28520GNAT and other Ada systems. The following are specific items which 28521have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 28522compilers, but do not affect porting code to GNAT. 28523(As of January 2007, GNAT is the only compiler available for Ada 2005; 28524the following issues may or may not arise for Ada 2005 programs 28525when other compilers appear.) 28526 28527 28528@itemize * 28529 28530@item 28531@emph{Ada 83 Pragmas and Attributes} 28532 28533Ada 95 compilers are allowed, but not required, to implement the missing 28534Ada 83 pragmas and attributes that are no longer defined in Ada 95. 28535GNAT implements all such pragmas and attributes, eliminating this as 28536a compatibility concern, but some other Ada 95 compilers reject these 28537pragmas and attributes. 28538 28539@item 28540@emph{Specialized Needs Annexes} 28541 28542GNAT implements the full set of special needs annexes. At the 28543current time, it is the only Ada 95 compiler to do so. This means that 28544programs making use of these features may not be portable to other Ada 2854595 compilation systems. 28546 28547@item 28548@emph{Representation Clauses} 28549 28550Some other Ada 95 compilers implement only the minimal set of 28551representation clauses required by the Ada 95 reference manual. GNAT goes 28552far beyond this minimal set, as described in the next section. 28553@end itemize 28554 28555@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 28556@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{404}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{407} 28557@section Representation Clauses 28558 28559 28560The Ada 83 reference manual was quite vague in describing both the minimal 28561required implementation of representation clauses, and also their precise 28562effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 28563minimal set of capabilities required is still quite limited. 28564 28565GNAT implements the full required set of capabilities in 28566Ada 95 and Ada 2005, but also goes much further, and in particular 28567an effort has been made to be compatible with existing Ada 83 usage to the 28568greatest extent possible. 28569 28570A few cases exist in which Ada 83 compiler behavior is incompatible with 28571the requirements in Ada 95 (and thus also Ada 2005). These are instances of 28572intentional or accidental dependence on specific implementation dependent 28573characteristics of these Ada 83 compilers. The following is a list of 28574the cases most likely to arise in existing Ada 83 code. 28575 28576 28577@itemize * 28578 28579@item 28580@emph{Implicit Packing} 28581 28582Some Ada 83 compilers allowed a Size specification to cause implicit 28583packing of an array or record. This could cause expensive implicit 28584conversions for change of representation in the presence of derived 28585types, and the Ada design intends to avoid this possibility. 28586Subsequent AI's were issued to make it clear that such implicit 28587change of representation in response to a Size clause is inadvisable, 28588and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 28589Reference Manuals as implementation advice that is followed by GNAT. 28590The problem will show up as an error 28591message rejecting the size clause. The fix is simply to provide 28592the explicit pragma @cite{Pack}, or for more fine tuned control, provide 28593a Component_Size clause. 28594 28595@item 28596@emph{Meaning of Size Attribute} 28597 28598The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 28599the minimal number of bits required to hold values of the type. For example, 28600on a 32-bit machine, the size of @cite{Natural} will typically be 31 and not 2860132 (since no sign bit is required). Some Ada 83 compilers gave 31, and 28602some 32 in this situation. This problem will usually show up as a compile 28603time error, but not always. It is a good idea to check all uses of the 28604'Size attribute when porting Ada 83 code. The GNAT specific attribute 28605Object_Size can provide a useful way of duplicating the behavior of 28606some Ada 83 compiler systems. 28607 28608@item 28609@emph{Size of Access Types} 28610 28611A common assumption in Ada 83 code is that an access type is in fact a pointer, 28612and that therefore it will be the same size as a System.Address value. This 28613assumption is true for GNAT in most cases with one exception. For the case of 28614a pointer to an unconstrained array type (where the bounds may vary from one 28615value of the access type to another), the default is to use a 'fat pointer', 28616which is represented as two separate pointers, one to the bounds, and one to 28617the array. This representation has a number of advantages, including improved 28618efficiency. However, it may cause some difficulties in porting existing Ada 83 28619code which makes the assumption that, for example, pointers fit in 32 bits on 28620a machine with 32-bit addressing. 28621 28622To get around this problem, GNAT also permits the use of 'thin pointers' for 28623access types in this case (where the designated type is an unconstrained array 28624type). These thin pointers are indeed the same size as a System.Address value. 28625To specify a thin pointer, use a size clause for the type, for example: 28626 28627@example 28628type X is access all String; 28629for X'Size use Standard'Address_Size; 28630@end example 28631 28632which will cause the type X to be represented using a single pointer. 28633When using this representation, the bounds are right behind the array. 28634This representation is slightly less efficient, and does not allow quite 28635such flexibility in the use of foreign pointers or in using the 28636Unrestricted_Access attribute to create pointers to non-aliased objects. 28637But for any standard portable use of the access type it will work in 28638a functionally correct manner and allow porting of existing code. 28639Note that another way of forcing a thin pointer representation 28640is to use a component size clause for the element size in an array, 28641or a record representation clause for an access field in a record. 28642 28643See the documentation of Unrestricted_Access in the GNAT RM for a 28644full discussion of possible problems using this attribute in conjunction 28645with thin pointers. 28646@end itemize 28647 28648@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 28649@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{408}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{409} 28650@section Compatibility with HP Ada 83 28651 28652 28653All the HP Ada 83 pragmas and attributes are recognized, although only a subset 28654of them can sensibly be implemented. The description of pragmas in 28655@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 28656applicable to GNAT. 28657 28658 28659@itemize * 28660 28661@item 28662@emph{Default floating-point representation} 28663 28664In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 28665it is VMS format. 28666 28667@item 28668@emph{System} 28669 28670the package System in GNAT exactly corresponds to the definition in the 28671Ada 95 reference manual, which means that it excludes many of the 28672HP Ada 83 extensions. However, a separate package Aux_DEC is provided 28673that contains the additional definitions, and a special pragma, 28674Extend_System allows this package to be treated transparently as an 28675extension of package System. 28676@end itemize 28677 28678@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 28679@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{40a}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{40b} 28680@chapter GNU Free Documentation License 28681 28682 28683Version 1.3, 3 November 2008 28684 28685Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 28686@indicateurl{http://fsf.org/} 28687 28688Everyone is permitted to copy and distribute verbatim copies of this 28689license document, but changing it is not allowed. 28690 28691@strong{Preamble} 28692 28693The purpose of this License is to make a manual, textbook, or other 28694functional and useful document "free" in the sense of freedom: to 28695assure everyone the effective freedom to copy and redistribute it, 28696with or without modifying it, either commercially or noncommercially. 28697Secondarily, this License preserves for the author and publisher a way 28698to get credit for their work, while not being considered responsible 28699for modifications made by others. 28700 28701This License is a kind of "copyleft", which means that derivative 28702works of the document must themselves be free in the same sense. It 28703complements the GNU General Public License, which is a copyleft 28704license designed for free software. 28705 28706We have designed this License in order to use it for manuals for free 28707software, because free software needs free documentation: a free 28708program should come with manuals providing the same freedoms that the 28709software does. But this License is not limited to software manuals; 28710it can be used for any textual work, regardless of subject matter or 28711whether it is published as a printed book. We recommend this License 28712principally for works whose purpose is instruction or reference. 28713 28714@strong{1. APPLICABILITY AND DEFINITIONS} 28715 28716This License applies to any manual or other work, in any medium, that 28717contains a notice placed by the copyright holder saying it can be 28718distributed under the terms of this License. Such a notice grants a 28719world-wide, royalty-free license, unlimited in duration, to use that 28720work under the conditions stated herein. The @strong{Document}, below, 28721refers to any such manual or work. Any member of the public is a 28722licensee, and is addressed as "@strong{you}". You accept the license if you 28723copy, modify or distribute the work in a way requiring permission 28724under copyright law. 28725 28726A "@strong{Modified Version}" of the Document means any work containing the 28727Document or a portion of it, either copied verbatim, or with 28728modifications and/or translated into another language. 28729 28730A "@strong{Secondary Section}" is a named appendix or a front-matter section of 28731the Document that deals exclusively with the relationship of the 28732publishers or authors of the Document to the Document's overall subject 28733(or to related matters) and contains nothing that could fall directly 28734within that overall subject. (Thus, if the Document is in part a 28735textbook of mathematics, a Secondary Section may not explain any 28736mathematics.) The relationship could be a matter of historical 28737connection with the subject or with related matters, or of legal, 28738commercial, philosophical, ethical or political position regarding 28739them. 28740 28741The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 28742are designated, as being those of Invariant Sections, in the notice 28743that says that the Document is released under this License. If a 28744section does not fit the above definition of Secondary then it is not 28745allowed to be designated as Invariant. The Document may contain zero 28746Invariant Sections. If the Document does not identify any Invariant 28747Sections then there are none. 28748 28749The "@strong{Cover Texts}" are certain short passages of text that are listed, 28750as Front-Cover Texts or Back-Cover Texts, in the notice that says that 28751the Document is released under this License. A Front-Cover Text may 28752be at most 5 words, and a Back-Cover Text may be at most 25 words. 28753 28754A "@strong{Transparent}" copy of the Document means a machine-readable copy, 28755represented in a format whose specification is available to the 28756general public, that is suitable for revising the document 28757straightforwardly with generic text editors or (for images composed of 28758pixels) generic paint programs or (for drawings) some widely available 28759drawing editor, and that is suitable for input to text formatters or 28760for automatic translation to a variety of formats suitable for input 28761to text formatters. A copy made in an otherwise Transparent file 28762format whose markup, or absence of markup, has been arranged to thwart 28763or discourage subsequent modification by readers is not Transparent. 28764An image format is not Transparent if used for any substantial amount 28765of text. A copy that is not "Transparent" is called @strong{Opaque}. 28766 28767Examples of suitable formats for Transparent copies include plain 28768ASCII without markup, Texinfo input format, LaTeX input format, SGML 28769or XML using a publicly available DTD, and standard-conforming simple 28770HTML, PostScript or PDF designed for human modification. Examples of 28771transparent image formats include PNG, XCF and JPG. Opaque formats 28772include proprietary formats that can be read and edited only by 28773proprietary word processors, SGML or XML for which the DTD and/or 28774processing tools are not generally available, and the 28775machine-generated HTML, PostScript or PDF produced by some word 28776processors for output purposes only. 28777 28778The "@strong{Title Page}" means, for a printed book, the title page itself, 28779plus such following pages as are needed to hold, legibly, the material 28780this License requires to appear in the title page. For works in 28781formats which do not have any title page as such, "Title Page" means 28782the text near the most prominent appearance of the work's title, 28783preceding the beginning of the body of the text. 28784 28785The "@strong{publisher}" means any person or entity that distributes 28786copies of the Document to the public. 28787 28788A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 28789title either is precisely XYZ or contains XYZ in parentheses following 28790text that translates XYZ in another language. (Here XYZ stands for a 28791specific section name mentioned below, such as "@strong{Acknowledgements}", 28792"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 28793To "@strong{Preserve the Title}" 28794of such a section when you modify the Document means that it remains a 28795section "Entitled XYZ" according to this definition. 28796 28797The Document may include Warranty Disclaimers next to the notice which 28798states that this License applies to the Document. These Warranty 28799Disclaimers are considered to be included by reference in this 28800License, but only as regards disclaiming warranties: any other 28801implication that these Warranty Disclaimers may have is void and has 28802no effect on the meaning of this License. 28803 28804@strong{2. VERBATIM COPYING} 28805 28806You may copy and distribute the Document in any medium, either 28807commercially or noncommercially, provided that this License, the 28808copyright notices, and the license notice saying this License applies 28809to the Document are reproduced in all copies, and that you add no other 28810conditions whatsoever to those of this License. You may not use 28811technical measures to obstruct or control the reading or further 28812copying of the copies you make or distribute. However, you may accept 28813compensation in exchange for copies. If you distribute a large enough 28814number of copies you must also follow the conditions in section 3. 28815 28816You may also lend copies, under the same conditions stated above, and 28817you may publicly display copies. 28818 28819@strong{3. COPYING IN QUANTITY} 28820 28821If you publish printed copies (or copies in media that commonly have 28822printed covers) of the Document, numbering more than 100, and the 28823Document's license notice requires Cover Texts, you must enclose the 28824copies in covers that carry, clearly and legibly, all these Cover 28825Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 28826the back cover. Both covers must also clearly and legibly identify 28827you as the publisher of these copies. The front cover must present 28828the full title with all words of the title equally prominent and 28829visible. You may add other material on the covers in addition. 28830Copying with changes limited to the covers, as long as they preserve 28831the title of the Document and satisfy these conditions, can be treated 28832as verbatim copying in other respects. 28833 28834If the required texts for either cover are too voluminous to fit 28835legibly, you should put the first ones listed (as many as fit 28836reasonably) on the actual cover, and continue the rest onto adjacent 28837pages. 28838 28839If you publish or distribute Opaque copies of the Document numbering 28840more than 100, you must either include a machine-readable Transparent 28841copy along with each Opaque copy, or state in or with each Opaque copy 28842a computer-network location from which the general network-using 28843public has access to download using public-standard network protocols 28844a complete Transparent copy of the Document, free of added material. 28845If you use the latter option, you must take reasonably prudent steps, 28846when you begin distribution of Opaque copies in quantity, to ensure 28847that this Transparent copy will remain thus accessible at the stated 28848location until at least one year after the last time you distribute an 28849Opaque copy (directly or through your agents or retailers) of that 28850edition to the public. 28851 28852It is requested, but not required, that you contact the authors of the 28853Document well before redistributing any large number of copies, to give 28854them a chance to provide you with an updated version of the Document. 28855 28856@strong{4. MODIFICATIONS} 28857 28858You may copy and distribute a Modified Version of the Document under 28859the conditions of sections 2 and 3 above, provided that you release 28860the Modified Version under precisely this License, with the Modified 28861Version filling the role of the Document, thus licensing distribution 28862and modification of the Modified Version to whoever possesses a copy 28863of it. In addition, you must do these things in the Modified Version: 28864 28865 28866@enumerate A 28867 28868@item 28869Use in the Title Page (and on the covers, if any) a title distinct 28870from that of the Document, and from those of previous versions 28871(which should, if there were any, be listed in the History section 28872of the Document). You may use the same title as a previous version 28873if the original publisher of that version gives permission. 28874 28875@item 28876List on the Title Page, as authors, one or more persons or entities 28877responsible for authorship of the modifications in the Modified 28878Version, together with at least five of the principal authors of the 28879Document (all of its principal authors, if it has fewer than five), 28880unless they release you from this requirement. 28881 28882@item 28883State on the Title page the name of the publisher of the 28884Modified Version, as the publisher. 28885 28886@item 28887Preserve all the copyright notices of the Document. 28888 28889@item 28890Add an appropriate copyright notice for your modifications 28891adjacent to the other copyright notices. 28892 28893@item 28894Include, immediately after the copyright notices, a license notice 28895giving the public permission to use the Modified Version under the 28896terms of this License, in the form shown in the Addendum below. 28897 28898@item 28899Preserve in that license notice the full lists of Invariant Sections 28900and required Cover Texts given in the Document's license notice. 28901 28902@item 28903Include an unaltered copy of this License. 28904 28905@item 28906Preserve the section Entitled "History", Preserve its Title, and add 28907to it an item stating at least the title, year, new authors, and 28908publisher of the Modified Version as given on the Title Page. If 28909there is no section Entitled "History" in the Document, create one 28910stating the title, year, authors, and publisher of the Document as 28911given on its Title Page, then add an item describing the Modified 28912Version as stated in the previous sentence. 28913 28914@item 28915Preserve the network location, if any, given in the Document for 28916public access to a Transparent copy of the Document, and likewise 28917the network locations given in the Document for previous versions 28918it was based on. These may be placed in the "History" section. 28919You may omit a network location for a work that was published at 28920least four years before the Document itself, or if the original 28921publisher of the version it refers to gives permission. 28922 28923@item 28924For any section Entitled "Acknowledgements" or "Dedications", 28925Preserve the Title of the section, and preserve in the section all 28926the substance and tone of each of the contributor acknowledgements 28927and/or dedications given therein. 28928 28929@item 28930Preserve all the Invariant Sections of the Document, 28931unaltered in their text and in their titles. Section numbers 28932or the equivalent are not considered part of the section titles. 28933 28934@item 28935Delete any section Entitled "Endorsements". Such a section 28936may not be included in the Modified Version. 28937 28938@item 28939Do not retitle any existing section to be Entitled "Endorsements" 28940or to conflict in title with any Invariant Section. 28941 28942@item 28943Preserve any Warranty Disclaimers. 28944@end enumerate 28945 28946If the Modified Version includes new front-matter sections or 28947appendices that qualify as Secondary Sections and contain no material 28948copied from the Document, you may at your option designate some or all 28949of these sections as invariant. To do this, add their titles to the 28950list of Invariant Sections in the Modified Version's license notice. 28951These titles must be distinct from any other section titles. 28952 28953You may add a section Entitled "Endorsements", provided it contains 28954nothing but endorsements of your Modified Version by various 28955parties---for example, statements of peer review or that the text has 28956been approved by an organization as the authoritative definition of a 28957standard. 28958 28959You may add a passage of up to five words as a Front-Cover Text, and a 28960passage of up to 25 words as a Back-Cover Text, to the end of the list 28961of Cover Texts in the Modified Version. Only one passage of 28962Front-Cover Text and one of Back-Cover Text may be added by (or 28963through arrangements made by) any one entity. If the Document already 28964includes a cover text for the same cover, previously added by you or 28965by arrangement made by the same entity you are acting on behalf of, 28966you may not add another; but you may replace the old one, on explicit 28967permission from the previous publisher that added the old one. 28968 28969The author(s) and publisher(s) of the Document do not by this License 28970give permission to use their names for publicity for or to assert or 28971imply endorsement of any Modified Version. 28972 28973@strong{5. COMBINING DOCUMENTS} 28974 28975You may combine the Document with other documents released under this 28976License, under the terms defined in section 4 above for modified 28977versions, provided that you include in the combination all of the 28978Invariant Sections of all of the original documents, unmodified, and 28979list them all as Invariant Sections of your combined work in its 28980license notice, and that you preserve all their Warranty Disclaimers. 28981 28982The combined work need only contain one copy of this License, and 28983multiple identical Invariant Sections may be replaced with a single 28984copy. If there are multiple Invariant Sections with the same name but 28985different contents, make the title of each such section unique by 28986adding at the end of it, in parentheses, the name of the original 28987author or publisher of that section if known, or else a unique number. 28988Make the same adjustment to the section titles in the list of 28989Invariant Sections in the license notice of the combined work. 28990 28991In the combination, you must combine any sections Entitled "History" 28992in the various original documents, forming one section Entitled 28993"History"; likewise combine any sections Entitled "Acknowledgements", 28994and any sections Entitled "Dedications". You must delete all sections 28995Entitled "Endorsements". 28996 28997@strong{6. COLLECTIONS OF DOCUMENTS} 28998 28999You may make a collection consisting of the Document and other documents 29000released under this License, and replace the individual copies of this 29001License in the various documents with a single copy that is included in 29002the collection, provided that you follow the rules of this License for 29003verbatim copying of each of the documents in all other respects. 29004 29005You may extract a single document from such a collection, and distribute 29006it individually under this License, provided you insert a copy of this 29007License into the extracted document, and follow this License in all 29008other respects regarding verbatim copying of that document. 29009 29010@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29011 29012A compilation of the Document or its derivatives with other separate 29013and independent documents or works, in or on a volume of a storage or 29014distribution medium, is called an "aggregate" if the copyright 29015resulting from the compilation is not used to limit the legal rights 29016of the compilation's users beyond what the individual works permit. 29017When the Document is included in an aggregate, this License does not 29018apply to the other works in the aggregate which are not themselves 29019derivative works of the Document. 29020 29021If the Cover Text requirement of section 3 is applicable to these 29022copies of the Document, then if the Document is less than one half of 29023the entire aggregate, the Document's Cover Texts may be placed on 29024covers that bracket the Document within the aggregate, or the 29025electronic equivalent of covers if the Document is in electronic form. 29026Otherwise they must appear on printed covers that bracket the whole 29027aggregate. 29028 29029@strong{8. TRANSLATION} 29030 29031Translation is considered a kind of modification, so you may 29032distribute translations of the Document under the terms of section 4. 29033Replacing Invariant Sections with translations requires special 29034permission from their copyright holders, but you may include 29035translations of some or all Invariant Sections in addition to the 29036original versions of these Invariant Sections. You may include a 29037translation of this License, and all the license notices in the 29038Document, and any Warranty Disclaimers, provided that you also include 29039the original English version of this License and the original versions 29040of those notices and disclaimers. In case of a disagreement between 29041the translation and the original version of this License or a notice 29042or disclaimer, the original version will prevail. 29043 29044If a section in the Document is Entitled "Acknowledgements", 29045"Dedications", or "History", the requirement (section 4) to Preserve 29046its Title (section 1) will typically require changing the actual 29047title. 29048 29049@strong{9. TERMINATION} 29050 29051You may not copy, modify, sublicense, or distribute the Document 29052except as expressly provided under this License. Any attempt 29053otherwise to copy, modify, sublicense, or distribute it is void, and 29054will automatically terminate your rights under this License. 29055 29056However, if you cease all violation of this License, then your license 29057from a particular copyright holder is reinstated (a) provisionally, 29058unless and until the copyright holder explicitly and finally 29059terminates your license, and (b) permanently, if the copyright holder 29060fails to notify you of the violation by some reasonable means prior to 2906160 days after the cessation. 29062 29063Moreover, your license from a particular copyright holder is 29064reinstated permanently if the copyright holder notifies you of the 29065violation by some reasonable means, this is the first time you have 29066received notice of violation of this License (for any work) from that 29067copyright holder, and you cure the violation prior to 30 days after 29068your receipt of the notice. 29069 29070Termination of your rights under this section does not terminate the 29071licenses of parties who have received copies or rights from you under 29072this License. If your rights have been terminated and not permanently 29073reinstated, receipt of a copy of some or all of the same material does 29074not give you any rights to use it. 29075 29076@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29077 29078The Free Software Foundation may publish new, revised versions 29079of the GNU Free Documentation License from time to time. Such new 29080versions will be similar in spirit to the present version, but may 29081differ in detail to address new problems or concerns. See 29082@indicateurl{http://www.gnu.org/copyleft/}. 29083 29084Each version of the License is given a distinguishing version number. 29085If the Document specifies that a particular numbered version of this 29086License "or any later version" applies to it, you have the option of 29087following the terms and conditions either of that specified version or 29088of any later version that has been published (not as a draft) by the 29089Free Software Foundation. If the Document does not specify a version 29090number of this License, you may choose any version ever published (not 29091as a draft) by the Free Software Foundation. If the Document 29092specifies that a proxy can decide which future versions of this 29093License can be used, that proxy's public statement of acceptance of a 29094version permanently authorizes you to choose that version for the 29095Document. 29096 29097@strong{11. RELICENSING} 29098 29099"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 29100World Wide Web server that publishes copyrightable works and also 29101provides prominent facilities for anybody to edit those works. A 29102public wiki that anybody can edit is an example of such a server. A 29103"Massive Multiauthor Collaboration" (or "MMC") contained in the 29104site means any set of copyrightable works thus published on the MMC 29105site. 29106 29107"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 29108license published by Creative Commons Corporation, a not-for-profit 29109corporation with a principal place of business in San Francisco, 29110California, as well as future copyleft versions of that license 29111published by that same organization. 29112 29113"Incorporate" means to publish or republish a Document, in whole or 29114in part, as part of another Document. 29115 29116An MMC is "eligible for relicensing" if it is licensed under this 29117License, and if all works that were first published under this License 29118somewhere other than this MMC, and subsequently incorporated in whole 29119or in part into the MMC, (1) had no cover texts or invariant sections, 29120and (2) were thus incorporated prior to November 1, 2008. 29121 29122The operator of an MMC Site may republish an MMC contained in the site 29123under CC-BY-SA on the same site at any time before August 1, 2009, 29124provided the MMC is eligible for relicensing. 29125 29126@strong{ADDENDUM: How to use this License for your documents} 29127 29128To use this License in a document you have written, include a copy of 29129the License in the document and put the following copyright and 29130license notices just after the title page: 29131 29132@quotation 29133 29134Copyright © YEAR YOUR NAME. 29135Permission is granted to copy, distribute and/or modify this document 29136under the terms of the GNU Free Documentation License, Version 1.3 29137or any later version published by the Free Software Foundation; 29138with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 29139A copy of the license is included in the section entitled "GNU 29140Free Documentation License". 29141@end quotation 29142 29143If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 29144replace the "with ... Texts." line with this: 29145 29146@quotation 29147 29148with the Invariant Sections being LIST THEIR TITLES, with the 29149Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 29150@end quotation 29151 29152If you have Invariant Sections without Cover Texts, or some other 29153combination of the three, merge those two alternatives to suit the 29154situation. 29155 29156If your document contains nontrivial examples of program code, we 29157recommend releasing these examples in parallel under your choice of 29158free software license, such as the GNU General Public License, 29159to permit their use in free software. 29160 29161@node Index,,GNU Free Documentation License,Top 29162@unnumbered Index 29163 29164 29165@printindex ge 29166 29167 29168@c %**end of body 29169@bye 29170