1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gnat_rm.info 4@documentencoding UTF-8 5@ifinfo 6@*Generated by Sphinx 1.4.6.@* 7@end ifinfo 8@settitle GNAT Reference Manual 9@defindex ge 10@paragraphindent 0 11@exampleindent 4 12@finalout 13@dircategory GNU Ada Tools 14@direntry 15* gnat_rm: (gnat_rm.info). gnat_rm 16@end direntry 17 18@definfoenclose strong,`,' 19@definfoenclose emph,`,' 20@c %**end of header 21 22@copying 23@quotation 24GNAT Reference Manual , Dec 10, 2019 25 26AdaCore 27 28Copyright @copyright{} 2008-2020, Free Software Foundation 29@end quotation 30 31@end copying 32 33@titlepage 34@title GNAT Reference Manual 35@insertcopying 36@end titlepage 37@contents 38 39@c %** start of user preamble 40 41@c %** end of user preamble 42 43@ifnottex 44@node Top 45@top GNAT Reference Manual 46@insertcopying 47@end ifnottex 48 49@c %**start of body 50@anchor{gnat_rm doc}@anchor{0} 51@emph{GNAT, The GNU Ada Development Environment} 52 53 54@include gcc-common.texi 55GCC version @value{version-GCC}@* 56AdaCore 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.3 or 60any later version published by the Free Software Foundation; with no 61Invariant Sections, with the Front-Cover Texts being "GNAT Reference 62Manual", and with no Back-Cover Texts. A copy of the license is 63included in the section entitled @ref{1,,GNU Free Documentation License}. 64 65@menu 66* About This Guide:: 67* Implementation Defined Pragmas:: 68* Implementation Defined Aspects:: 69* Implementation Defined Attributes:: 70* Standard and Implementation Defined Restrictions:: 71* Implementation Advice:: 72* Implementation Defined Characteristics:: 73* Intrinsic Subprograms:: 74* Representation Clauses and Pragmas:: 75* Standard Library Routines:: 76* The Implementation of Standard I/O:: 77* The GNAT Library:: 78* Interfacing to Other Languages:: 79* Specialized Needs Annexes:: 80* Implementation of Specific Ada Features:: 81* Implementation of Ada 2012 Features:: 82* Obsolescent Features:: 83* Compatibility and Porting Guide:: 84* GNU Free Documentation License:: 85* Index:: 86 87@detailmenu 88 --- The Detailed Node Listing --- 89 90About This Guide 91 92* What This Reference Manual Contains:: 93* Conventions:: 94* Related Information:: 95 96Implementation Defined Pragmas 97 98* Pragma Abort_Defer:: 99* Pragma Abstract_State:: 100* Pragma Acc_Parallel:: 101* Pragma Acc_Loop:: 102* Pragma Acc_Kernels:: 103* Pragma Acc_Data:: 104* Pragma Ada_83:: 105* Pragma Ada_95:: 106* Pragma Ada_05:: 107* Pragma Ada_2005:: 108* Pragma Ada_12:: 109* Pragma Ada_2012:: 110* Pragma Aggregate_Individually_Assign:: 111* Pragma Allow_Integer_Address:: 112* Pragma Annotate:: 113* Pragma Assert:: 114* Pragma Assert_And_Cut:: 115* Pragma Assertion_Policy:: 116* Pragma Assume:: 117* Pragma Assume_No_Invalid_Values:: 118* Pragma Async_Readers:: 119* Pragma Async_Writers:: 120* Pragma Attribute_Definition:: 121* Pragma C_Pass_By_Copy:: 122* Pragma Check:: 123* Pragma Check_Float_Overflow:: 124* Pragma Check_Name:: 125* Pragma Check_Policy:: 126* Pragma Comment:: 127* Pragma Common_Object:: 128* Pragma Compile_Time_Error:: 129* Pragma Compile_Time_Warning:: 130* Pragma Compiler_Unit:: 131* Pragma Compiler_Unit_Warning:: 132* Pragma Complete_Representation:: 133* Pragma Complex_Representation:: 134* Pragma Component_Alignment:: 135* Pragma Constant_After_Elaboration:: 136* Pragma Contract_Cases:: 137* Pragma Convention_Identifier:: 138* Pragma CPP_Class:: 139* Pragma CPP_Constructor:: 140* Pragma CPP_Virtual:: 141* Pragma CPP_Vtable:: 142* Pragma CPU:: 143* Pragma Deadline_Floor:: 144* Pragma Default_Initial_Condition:: 145* Pragma Debug:: 146* Pragma Debug_Policy:: 147* Pragma Default_Scalar_Storage_Order:: 148* Pragma Default_Storage_Pool:: 149* Pragma Depends:: 150* Pragma Detect_Blocking:: 151* Pragma Disable_Atomic_Synchronization:: 152* Pragma Dispatching_Domain:: 153* Pragma Effective_Reads:: 154* Pragma Effective_Writes:: 155* Pragma Elaboration_Checks:: 156* Pragma Eliminate:: 157* Pragma Enable_Atomic_Synchronization:: 158* Pragma Export_Function:: 159* Pragma Export_Object:: 160* Pragma Export_Procedure:: 161* Pragma Export_Value:: 162* Pragma Export_Valued_Procedure:: 163* Pragma Extend_System:: 164* Pragma Extensions_Allowed:: 165* Pragma Extensions_Visible:: 166* Pragma External:: 167* Pragma External_Name_Casing:: 168* Pragma Fast_Math:: 169* Pragma Favor_Top_Level:: 170* Pragma Finalize_Storage_Only:: 171* Pragma Float_Representation:: 172* Pragma Ghost:: 173* Pragma Global:: 174* Pragma Ident:: 175* Pragma Ignore_Pragma:: 176* Pragma Implementation_Defined:: 177* Pragma Implemented:: 178* Pragma Implicit_Packing:: 179* Pragma Import_Function:: 180* Pragma Import_Object:: 181* Pragma Import_Procedure:: 182* Pragma Import_Valued_Procedure:: 183* Pragma Independent:: 184* Pragma Independent_Components:: 185* Pragma Initial_Condition:: 186* Pragma Initialize_Scalars:: 187* Pragma Initializes:: 188* Pragma Inline_Always:: 189* Pragma Inline_Generic:: 190* Pragma Interface:: 191* Pragma Interface_Name:: 192* Pragma Interrupt_Handler:: 193* Pragma Interrupt_State:: 194* Pragma Invariant:: 195* Pragma Keep_Names:: 196* Pragma License:: 197* Pragma Link_With:: 198* Pragma Linker_Alias:: 199* Pragma Linker_Constructor:: 200* Pragma Linker_Destructor:: 201* Pragma Linker_Section:: 202* Pragma Lock_Free:: 203* Pragma Loop_Invariant:: 204* Pragma Loop_Optimize:: 205* Pragma Loop_Variant:: 206* Pragma Machine_Attribute:: 207* Pragma Main:: 208* Pragma Main_Storage:: 209* Pragma Max_Queue_Length:: 210* Pragma No_Body:: 211* Pragma No_Caching:: 212* Pragma No_Component_Reordering:: 213* Pragma No_Elaboration_Code_All:: 214* Pragma No_Heap_Finalization:: 215* Pragma No_Inline:: 216* Pragma No_Return:: 217* Pragma No_Strict_Aliasing:: 218* Pragma No_Tagged_Streams:: 219* Pragma Normalize_Scalars:: 220* Pragma Obsolescent:: 221* Pragma Optimize_Alignment:: 222* Pragma Ordered:: 223* Pragma Overflow_Mode:: 224* Pragma Overriding_Renamings:: 225* Pragma Partition_Elaboration_Policy:: 226* Pragma Part_Of:: 227* Pragma Passive:: 228* Pragma Persistent_BSS:: 229* Pragma Polling:: 230* Pragma Post:: 231* Pragma Postcondition:: 232* Pragma Post_Class:: 233* Pragma Rename_Pragma:: 234* Pragma Pre:: 235* Pragma Precondition:: 236* Pragma Predicate:: 237* Pragma Predicate_Failure:: 238* Pragma Preelaborable_Initialization:: 239* Pragma Prefix_Exception_Messages:: 240* Pragma Pre_Class:: 241* Pragma Priority_Specific_Dispatching:: 242* Pragma Profile:: 243* Pragma Profile_Warnings:: 244* Pragma Propagate_Exceptions:: 245* Pragma Provide_Shift_Operators:: 246* Pragma Psect_Object:: 247* Pragma Pure_Function:: 248* Pragma Rational:: 249* Pragma Ravenscar:: 250* Pragma Refined_Depends:: 251* Pragma Refined_Global:: 252* Pragma Refined_Post:: 253* Pragma Refined_State:: 254* Pragma Relative_Deadline:: 255* Pragma Remote_Access_Type:: 256* Pragma Restricted_Run_Time:: 257* Pragma Restriction_Warnings:: 258* Pragma Reviewable:: 259* Pragma Secondary_Stack_Size:: 260* Pragma Share_Generic:: 261* Pragma Shared:: 262* Pragma Short_Circuit_And_Or:: 263* Pragma Short_Descriptors:: 264* Pragma Simple_Storage_Pool_Type:: 265* Pragma Source_File_Name:: 266* Pragma Source_File_Name_Project:: 267* Pragma Source_Reference:: 268* Pragma SPARK_Mode:: 269* Pragma Static_Elaboration_Desired:: 270* Pragma Stream_Convert:: 271* Pragma Style_Checks:: 272* Pragma Subtitle:: 273* Pragma Suppress:: 274* Pragma Suppress_All:: 275* Pragma Suppress_Debug_Info:: 276* Pragma Suppress_Exception_Locations:: 277* Pragma Suppress_Initialization:: 278* Pragma Task_Name:: 279* Pragma Task_Storage:: 280* Pragma Test_Case:: 281* Pragma Thread_Local_Storage:: 282* Pragma Time_Slice:: 283* Pragma Title:: 284* Pragma Type_Invariant:: 285* Pragma Type_Invariant_Class:: 286* Pragma Unchecked_Union:: 287* Pragma Unevaluated_Use_Of_Old:: 288* Pragma Unimplemented_Unit:: 289* Pragma Universal_Aliasing:: 290* Pragma Universal_Data:: 291* Pragma Unmodified:: 292* Pragma Unreferenced:: 293* Pragma Unreferenced_Objects:: 294* Pragma Unreserve_All_Interrupts:: 295* Pragma Unsuppress:: 296* Pragma Use_VADS_Size:: 297* Pragma Unused:: 298* Pragma Validity_Checks:: 299* Pragma Volatile:: 300* Pragma Volatile_Full_Access:: 301* Pragma Volatile_Function:: 302* Pragma Warning_As_Error:: 303* Pragma Warnings:: 304* Pragma Weak_External:: 305* Pragma Wide_Character_Encoding:: 306 307Implementation Defined Aspects 308 309* Aspect Abstract_State:: 310* Aspect Annotate:: 311* Aspect Async_Readers:: 312* Aspect Async_Writers:: 313* Aspect Constant_After_Elaboration:: 314* Aspect Contract_Cases:: 315* Aspect Depends:: 316* Aspect Default_Initial_Condition:: 317* Aspect Dimension:: 318* Aspect Dimension_System:: 319* Aspect Disable_Controlled:: 320* Aspect Effective_Reads:: 321* Aspect Effective_Writes:: 322* Aspect Extensions_Visible:: 323* Aspect Favor_Top_Level:: 324* Aspect Ghost:: 325* Aspect Global:: 326* Aspect Initial_Condition:: 327* Aspect Initializes:: 328* Aspect Inline_Always:: 329* Aspect Invariant:: 330* Aspect Invariant'Class:: 331* Aspect Iterable:: 332* Aspect Linker_Section:: 333* Aspect Lock_Free:: 334* Aspect Max_Queue_Length:: 335* Aspect No_Caching:: 336* Aspect No_Elaboration_Code_All:: 337* Aspect No_Inline:: 338* Aspect No_Tagged_Streams:: 339* Aspect Object_Size:: 340* Aspect Obsolescent:: 341* Aspect Part_Of:: 342* Aspect Persistent_BSS:: 343* Aspect Predicate:: 344* Aspect Pure_Function:: 345* Aspect Refined_Depends:: 346* Aspect Refined_Global:: 347* Aspect Refined_Post:: 348* Aspect Refined_State:: 349* Aspect Remote_Access_Type:: 350* Aspect Secondary_Stack_Size:: 351* Aspect Scalar_Storage_Order:: 352* Aspect Shared:: 353* Aspect Simple_Storage_Pool:: 354* Aspect Simple_Storage_Pool_Type:: 355* Aspect SPARK_Mode:: 356* Aspect Suppress_Debug_Info:: 357* Aspect Suppress_Initialization:: 358* Aspect Test_Case:: 359* Aspect Thread_Local_Storage:: 360* Aspect Universal_Aliasing:: 361* Aspect Universal_Data:: 362* Aspect Unmodified:: 363* Aspect Unreferenced:: 364* Aspect Unreferenced_Objects:: 365* Aspect Value_Size:: 366* Aspect Volatile_Full_Access:: 367* Aspect Volatile_Function:: 368* Aspect Warnings:: 369 370Implementation Defined Attributes 371 372* Attribute Abort_Signal:: 373* Attribute Address_Size:: 374* Attribute Asm_Input:: 375* Attribute Asm_Output:: 376* Attribute Atomic_Always_Lock_Free:: 377* Attribute Bit:: 378* Attribute Bit_Position:: 379* Attribute Code_Address:: 380* Attribute Compiler_Version:: 381* Attribute Constrained:: 382* Attribute Default_Bit_Order:: 383* Attribute Default_Scalar_Storage_Order:: 384* Attribute Deref:: 385* Attribute Descriptor_Size:: 386* Attribute Elaborated:: 387* Attribute Elab_Body:: 388* Attribute Elab_Spec:: 389* Attribute Elab_Subp_Body:: 390* Attribute Emax:: 391* Attribute Enabled:: 392* Attribute Enum_Rep:: 393* Attribute Enum_Val:: 394* Attribute Epsilon:: 395* Attribute Fast_Math:: 396* Attribute Finalization_Size:: 397* Attribute Fixed_Value:: 398* Attribute From_Any:: 399* Attribute Has_Access_Values:: 400* Attribute Has_Discriminants:: 401* Attribute Img:: 402* Attribute Integer_Value:: 403* Attribute Invalid_Value:: 404* Attribute Iterable:: 405* Attribute Large:: 406* Attribute Library_Level:: 407* Attribute Lock_Free:: 408* Attribute Loop_Entry:: 409* Attribute Machine_Size:: 410* Attribute Mantissa:: 411* Attribute Maximum_Alignment:: 412* Attribute Mechanism_Code:: 413* Attribute Null_Parameter:: 414* Attribute Object_Size:: 415* Attribute Old:: 416* Attribute Passed_By_Reference:: 417* Attribute Pool_Address:: 418* Attribute Range_Length:: 419* Attribute Restriction_Set:: 420* Attribute Result:: 421* Attribute Safe_Emax:: 422* Attribute Safe_Large:: 423* Attribute Safe_Small:: 424* Attribute Scalar_Storage_Order:: 425* Attribute Simple_Storage_Pool:: 426* Attribute Small:: 427* Attribute Storage_Unit:: 428* Attribute Stub_Type:: 429* Attribute System_Allocator_Alignment:: 430* Attribute Target_Name:: 431* Attribute To_Address:: 432* Attribute To_Any:: 433* Attribute Type_Class:: 434* Attribute Type_Key:: 435* Attribute TypeCode:: 436* Attribute Unconstrained_Array:: 437* Attribute Universal_Literal_String:: 438* Attribute Unrestricted_Access:: 439* Attribute Update:: 440* Attribute Valid_Scalars:: 441* Attribute VADS_Size:: 442* Attribute Value_Size:: 443* Attribute Wchar_T_Size:: 444* Attribute Word_Size:: 445 446Standard and Implementation Defined Restrictions 447 448* Partition-Wide Restrictions:: 449* Program Unit Level Restrictions:: 450 451Partition-Wide Restrictions 452 453* Immediate_Reclamation:: 454* Max_Asynchronous_Select_Nesting:: 455* Max_Entry_Queue_Length:: 456* Max_Protected_Entries:: 457* Max_Select_Alternatives:: 458* Max_Storage_At_Blocking:: 459* Max_Task_Entries:: 460* Max_Tasks:: 461* No_Abort_Statements:: 462* No_Access_Parameter_Allocators:: 463* No_Access_Subprograms:: 464* No_Allocators:: 465* No_Anonymous_Allocators:: 466* No_Asynchronous_Control:: 467* No_Calendar:: 468* No_Coextensions:: 469* No_Default_Initialization:: 470* No_Delay:: 471* No_Dependence:: 472* No_Direct_Boolean_Operators:: 473* No_Dispatch:: 474* No_Dispatching_Calls:: 475* No_Dynamic_Attachment:: 476* No_Dynamic_Priorities:: 477* No_Entry_Calls_In_Elaboration_Code:: 478* No_Enumeration_Maps:: 479* No_Exception_Handlers:: 480* No_Exception_Propagation:: 481* No_Exception_Registration:: 482* No_Exceptions:: 483* No_Finalization:: 484* No_Fixed_Point:: 485* No_Floating_Point:: 486* No_Implicit_Conditionals:: 487* No_Implicit_Dynamic_Code:: 488* No_Implicit_Heap_Allocations:: 489* No_Implicit_Protected_Object_Allocations:: 490* No_Implicit_Task_Allocations:: 491* No_Initialize_Scalars:: 492* No_IO:: 493* No_Local_Allocators:: 494* No_Local_Protected_Objects:: 495* No_Local_Timing_Events:: 496* No_Long_Long_Integers:: 497* No_Multiple_Elaboration:: 498* No_Nested_Finalization:: 499* No_Protected_Type_Allocators:: 500* No_Protected_Types:: 501* No_Recursion:: 502* No_Reentrancy:: 503* No_Relative_Delay:: 504* No_Requeue_Statements:: 505* No_Secondary_Stack:: 506* No_Select_Statements:: 507* No_Specific_Termination_Handlers:: 508* No_Specification_of_Aspect:: 509* No_Standard_Allocators_After_Elaboration:: 510* No_Standard_Storage_Pools:: 511* No_Stream_Optimizations:: 512* No_Streams:: 513* No_Task_Allocators:: 514* No_Task_At_Interrupt_Priority:: 515* No_Task_Attributes_Package:: 516* No_Task_Hierarchy:: 517* No_Task_Termination:: 518* No_Tasking:: 519* No_Terminate_Alternatives:: 520* No_Unchecked_Access:: 521* No_Unchecked_Conversion:: 522* No_Unchecked_Deallocation:: 523* No_Use_Of_Entity:: 524* Pure_Barriers:: 525* Simple_Barriers:: 526* Static_Priorities:: 527* Static_Storage_Size:: 528 529Program Unit Level Restrictions 530 531* No_Elaboration_Code:: 532* No_Dynamic_Sized_Objects:: 533* No_Entry_Queue:: 534* No_Implementation_Aspect_Specifications:: 535* No_Implementation_Attributes:: 536* No_Implementation_Identifiers:: 537* No_Implementation_Pragmas:: 538* No_Implementation_Restrictions:: 539* No_Implementation_Units:: 540* No_Implicit_Aliasing:: 541* No_Implicit_Loops:: 542* No_Obsolescent_Features:: 543* No_Wide_Characters:: 544* Static_Dispatch_Tables:: 545* SPARK_05:: 546 547Implementation Advice 548 549* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 550* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 551* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 552* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 553* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 554* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 555* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 556* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 557* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 558* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 559* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 560* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 561* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 562* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 563* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 564* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 565* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 566* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 567* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 568* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 569* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 570* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 571* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 572* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 573* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 574* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 575* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 576* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 577* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 578* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 579* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 580* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 581* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 582* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 583* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 584* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 585* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 586* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 587* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 588* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 589* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 590* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 591* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 592* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 593* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 594* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 595* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 596* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 597* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 598* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 599* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 600* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 601* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 602* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 603* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 604* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 605* RM F(7); COBOL Support: RM F 7 COBOL Support. 606* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 607* RM G; Numerics: RM G Numerics. 608* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 609* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 610* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 611* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 612* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 613 614Intrinsic Subprograms 615 616* Intrinsic Operators:: 617* Compilation_ISO_Date:: 618* Compilation_Date:: 619* Compilation_Time:: 620* Enclosing_Entity:: 621* Exception_Information:: 622* Exception_Message:: 623* Exception_Name:: 624* File:: 625* Line:: 626* Shifts and Rotates:: 627* Source_Location:: 628 629Representation Clauses and Pragmas 630 631* Alignment Clauses:: 632* Size Clauses:: 633* Storage_Size Clauses:: 634* Size of Variant Record Objects:: 635* Biased Representation:: 636* Value_Size and Object_Size Clauses:: 637* Component_Size Clauses:: 638* Bit_Order Clauses:: 639* Effect of Bit_Order on Byte Ordering:: 640* Pragma Pack for Arrays:: 641* Pragma Pack for Records:: 642* Record Representation Clauses:: 643* Handling of Records with Holes:: 644* Enumeration Clauses:: 645* Address Clauses:: 646* Use of Address Clauses for Memory-Mapped I/O:: 647* Effect of Convention on Representation:: 648* Conventions and Anonymous Access Types:: 649* Determining the Representations chosen by GNAT:: 650 651The Implementation of Standard I/O 652 653* Standard I/O Packages:: 654* FORM Strings:: 655* Direct_IO:: 656* Sequential_IO:: 657* Text_IO:: 658* Wide_Text_IO:: 659* Wide_Wide_Text_IO:: 660* Stream_IO:: 661* Text Translation:: 662* Shared Files:: 663* Filenames encoding:: 664* File content encoding:: 665* Open Modes:: 666* Operations on C Streams:: 667* Interfacing to C Streams:: 668 669Text_IO 670 671* Stream Pointer Positioning:: 672* Reading and Writing Non-Regular Files:: 673* Get_Immediate:: 674* Treating Text_IO Files as Streams:: 675* Text_IO Extensions:: 676* Text_IO Facilities for Unbounded Strings:: 677 678Wide_Text_IO 679 680* Stream Pointer Positioning: Stream Pointer Positioning<2>. 681* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 682 683Wide_Wide_Text_IO 684 685* Stream Pointer Positioning: Stream Pointer Positioning<3>. 686* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 687 688The GNAT Library 689 690* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 691* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 692* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 693* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 694* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 695* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 696* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 697* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 698* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 699* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 700* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 701* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 702* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 703* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 704* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 705* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 706* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 707* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 708* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 709* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 710* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 711* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 712* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 713* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 714* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 715* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 716* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 717* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 718* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 719* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 720* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 721* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 722* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 723* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 724* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 725* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 726* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 727* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 728* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 729* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 730* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 731* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 732* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 733* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 734* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 735* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 736* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 737* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 738* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 739* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 740* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 741* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 742* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 743* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 744* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 745* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 746* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 747* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 748* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 749* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 750* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 751* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 752* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 753* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 754* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 755* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 756* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 757* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 758* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 759* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 760* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 761* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 762* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 763* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 764* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 765* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 766* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 767* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 768* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 769* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 770* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 771* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 772* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 773* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 774* GNAT.IO (g-io.ads): GNAT IO g-io ads. 775* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 776* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 777* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 778* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 779* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 780* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 781* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 782* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 783* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 784* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 785* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 786* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 787* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 788* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 789* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 790* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 791* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 792* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 793* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 794* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 795* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 796* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 797* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 798* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 799* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 800* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 801* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 802* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 803* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 804* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 805* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 806* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 807* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 808* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 809* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 810* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 811* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 812* GNAT.Table (g-table.ads): GNAT Table g-table ads. 813* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 814* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 815* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 816* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 817* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 818* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 819* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 820* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 821* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 822* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 823* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 824* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 825* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 826* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 827* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 828* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 829* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 830* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 831* System.Assertions (s-assert.ads): System Assertions s-assert ads. 832* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 833* System.Memory (s-memory.ads): System Memory s-memory ads. 834* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 835* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 836* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 837* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 838* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 839* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 840* System.Rident (s-rident.ads): System Rident s-rident ads. 841* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 842* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 843* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 844* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 845 846Interfacing to Other Languages 847 848* Interfacing to C:: 849* Interfacing to C++:: 850* Interfacing to COBOL:: 851* Interfacing to Fortran:: 852* Interfacing to non-GNAT Ada code:: 853 854Implementation of Specific Ada Features 855 856* Machine Code Insertions:: 857* GNAT Implementation of Tasking:: 858* GNAT Implementation of Shared Passive Packages:: 859* Code Generation for Array Aggregates:: 860* The Size of Discriminated Records with Default Discriminants:: 861* Strict Conformance to the Ada Reference Manual:: 862 863GNAT Implementation of Tasking 864 865* Mapping Ada Tasks onto the Underlying Kernel Threads:: 866* Ensuring Compliance with the Real-Time Annex:: 867* Support for Locking Policies:: 868 869Code Generation for Array Aggregates 870 871* Static constant aggregates with static bounds:: 872* Constant aggregates with unconstrained nominal types:: 873* Aggregates with static bounds:: 874* Aggregates with nonstatic bounds:: 875* Aggregates in assignment statements:: 876 877Obsolescent Features 878 879* pragma No_Run_Time:: 880* pragma Ravenscar:: 881* pragma Restricted_Run_Time:: 882* pragma Task_Info:: 883* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 884 885Compatibility and Porting Guide 886 887* Writing Portable Fixed-Point Declarations:: 888* Compatibility with Ada 83:: 889* Compatibility between Ada 95 and Ada 2005:: 890* Implementation-dependent characteristics:: 891* Compatibility with Other Ada Systems:: 892* Representation Clauses:: 893* Compatibility with HP Ada 83:: 894 895Compatibility with Ada 83 896 897* Legal Ada 83 programs that are illegal in Ada 95:: 898* More deterministic semantics:: 899* Changed semantics:: 900* Other language compatibility issues:: 901 902Implementation-dependent characteristics 903 904* Implementation-defined pragmas:: 905* Implementation-defined attributes:: 906* Libraries:: 907* Elaboration order:: 908* Target-specific aspects:: 909 910@end detailmenu 911@end menu 912 913@node About This Guide,Implementation Defined Pragmas,Top,Top 914@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} 915@chapter About This Guide 916 917 918 919This manual contains useful information in writing programs using the 920GNAT compiler. It includes information on implementation dependent 921characteristics of GNAT, including all the information required by 922Annex M of the Ada language standard. 923 924GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 925invoked in Ada 83 compatibility mode. 926By default, GNAT assumes Ada 2012, 927but you can override with a compiler switch 928to explicitly specify the language version. 929(Please refer to the @emph{GNAT User's Guide} for details on these switches.) 930Throughout this manual, references to 'Ada' without a year suffix 931apply to all the Ada versions of the language. 932 933Ada is designed to be highly portable. 934In general, a program will have the same effect even when compiled by 935different compilers on different platforms. 936However, since Ada is designed to be used in a 937wide variety of applications, it also contains a number of system 938dependent features to be used in interfacing to the external world. 939 940@geindex Implementation-dependent features 941 942@geindex Portability 943 944Note: Any program that makes use of implementation-dependent features 945may be non-portable. You should follow good programming practice and 946isolate and clearly document any sections of your program that make use 947of these features in a non-portable manner. 948 949@menu 950* What This Reference Manual Contains:: 951* Conventions:: 952* Related Information:: 953 954@end menu 955 956@node What This Reference Manual Contains,Conventions,,About This Guide 957@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 958@section What This Reference Manual Contains 959 960 961This reference manual contains the following chapters: 962 963 964@itemize * 965 966@item 967@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 968pragmas, which can be used to extend and enhance the functionality of the 969compiler. 970 971@item 972@ref{8,,Implementation Defined Attributes}, lists GNAT 973implementation-dependent attributes, which can be used to extend and 974enhance the functionality of the compiler. 975 976@item 977@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 978implementation-dependent restrictions, which can be used to extend and 979enhance the functionality of the compiler. 980 981@item 982@ref{a,,Implementation Advice}, provides information on generally 983desirable behavior which are not requirements that all compilers must 984follow since it cannot be provided on all systems, or which may be 985undesirable on some systems. 986 987@item 988@ref{b,,Implementation Defined Characteristics}, provides a guide to 989minimizing implementation dependent features. 990 991@item 992@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 993implemented by GNAT, and how they can be imported into user 994application programs. 995 996@item 997@ref{d,,Representation Clauses and Pragmas}, describes in detail the 998way that GNAT represents data, and in particular the exact set 999of representation clauses and pragmas that is accepted. 1000 1001@item 1002@ref{e,,Standard Library Routines}, provides a listing of packages and a 1003brief description of the functionality that is provided by Ada's 1004extensive set of standard library routines as implemented by GNAT. 1005 1006@item 1007@ref{f,,The Implementation of Standard I/O}, details how the GNAT 1008implementation of the input-output facilities. 1009 1010@item 1011@ref{10,,The GNAT Library}, is a catalog of packages that complement 1012the Ada predefined library. 1013 1014@item 1015@ref{11,,Interfacing to Other Languages}, describes how programs 1016written in Ada using GNAT can be interfaced to other programming 1017languages. 1018 1019@item 1020@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 1021of the specialized needs annexes. 1022 1023@item 1024@ref{13,,Implementation of Specific Ada Features}, discusses issues related 1025to GNAT's implementation of machine code insertions, tasking, and several 1026other features. 1027 1028@item 1029@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1030GNAT implementation of the Ada 2012 language standard. 1031 1032@item 1033@ref{15,,Obsolescent Features} documents implementation dependent features, 1034including pragmas and attributes, which are considered obsolescent, since 1035there are other preferred ways of achieving the same results. These 1036obsolescent forms are retained for backwards compatibility. 1037 1038@item 1039@ref{16,,Compatibility and Porting Guide} presents some guidelines for 1040developing portable Ada code, describes the compatibility issues that 1041may arise between GNAT and other Ada compilation systems (including those 1042for Ada 83), and shows how GNAT can expedite porting applications 1043developed in other Ada environments. 1044 1045@item 1046@ref{1,,GNU Free Documentation License} contains the license for this document. 1047@end itemize 1048 1049@geindex Ada 95 Language Reference Manual 1050 1051@geindex Ada 2005 Language Reference Manual 1052 1053This reference manual assumes a basic familiarity with the Ada 95 language, as 1054described in the 1055@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1056It does not require knowledge of the new features introduced by Ada 2005 or 1057Ada 2012. 1058All three reference manuals are included in the GNAT documentation 1059package. 1060 1061@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1062@anchor{gnat_rm/about_this_guide conventions}@anchor{17} 1063@section Conventions 1064 1065 1066@geindex Conventions 1067@geindex typographical 1068 1069@geindex Typographical conventions 1070 1071Following are examples of the typographical and graphic conventions used 1072in this guide: 1073 1074 1075@itemize * 1076 1077@item 1078@code{Functions}, @code{utility program names}, @code{standard names}, 1079and @code{classes}. 1080 1081@item 1082@code{Option flags} 1083 1084@item 1085@code{File names} 1086 1087@item 1088@code{Variables} 1089 1090@item 1091@emph{Emphasis} 1092 1093@item 1094[optional information or parameters] 1095 1096@item 1097Examples are described by text 1098 1099@example 1100and then shown this way. 1101@end example 1102 1103@item 1104Commands that are entered by the user are shown as preceded by a prompt string 1105comprising the @code{$} character followed by a space. 1106@end itemize 1107 1108@node Related Information,,Conventions,About This Guide 1109@anchor{gnat_rm/about_this_guide related-information}@anchor{18} 1110@section Related Information 1111 1112 1113See the following documents for further information on GNAT: 1114 1115 1116@itemize * 1117 1118@item 1119@cite{GNAT User's Guide for Native Platforms}, 1120which provides information on how to use the 1121GNAT development environment. 1122 1123@item 1124@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1125 1126@item 1127@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1128of the Ada 95 standard. The annotations describe 1129detailed aspects of the design decision, and in particular contain useful 1130sections on Ada 83 compatibility. 1131 1132@item 1133@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1134 1135@item 1136@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1137of the Ada 2005 standard. The annotations describe 1138detailed aspects of the design decision. 1139 1140@item 1141@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1142 1143@item 1144@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1145which contains specific information on compatibility between GNAT and 1146DEC Ada 83 systems. 1147 1148@item 1149@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1150describes in detail the pragmas and attributes provided by the DEC Ada 83 1151compiler system. 1152@end itemize 1153 1154@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1155@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} 1156@chapter Implementation Defined Pragmas 1157 1158 1159Ada defines a set of pragmas that can be used to supply additional 1160information to the compiler. These language defined pragmas are 1161implemented in GNAT and work as described in the Ada Reference Manual. 1162 1163In addition, Ada allows implementations to define additional pragmas 1164whose meaning is defined by the implementation. GNAT provides a number 1165of these implementation-defined pragmas, which can be used to extend 1166and enhance the functionality of the compiler. This section of the GNAT 1167Reference Manual describes these additional pragmas. 1168 1169Note that any program using these pragmas might not be portable to other 1170compilers (although GNAT implements this set of pragmas on all 1171platforms). Therefore if portability to other compilers is an important 1172consideration, the use of these pragmas should be minimized. 1173 1174@menu 1175* Pragma Abort_Defer:: 1176* Pragma Abstract_State:: 1177* Pragma Acc_Parallel:: 1178* Pragma Acc_Loop:: 1179* Pragma Acc_Kernels:: 1180* Pragma Acc_Data:: 1181* Pragma Ada_83:: 1182* Pragma Ada_95:: 1183* Pragma Ada_05:: 1184* Pragma Ada_2005:: 1185* Pragma Ada_12:: 1186* Pragma Ada_2012:: 1187* Pragma Aggregate_Individually_Assign:: 1188* Pragma Allow_Integer_Address:: 1189* Pragma Annotate:: 1190* Pragma Assert:: 1191* Pragma Assert_And_Cut:: 1192* Pragma Assertion_Policy:: 1193* Pragma Assume:: 1194* Pragma Assume_No_Invalid_Values:: 1195* Pragma Async_Readers:: 1196* Pragma Async_Writers:: 1197* Pragma Attribute_Definition:: 1198* Pragma C_Pass_By_Copy:: 1199* Pragma Check:: 1200* Pragma Check_Float_Overflow:: 1201* Pragma Check_Name:: 1202* Pragma Check_Policy:: 1203* Pragma Comment:: 1204* Pragma Common_Object:: 1205* Pragma Compile_Time_Error:: 1206* Pragma Compile_Time_Warning:: 1207* Pragma Compiler_Unit:: 1208* Pragma Compiler_Unit_Warning:: 1209* Pragma Complete_Representation:: 1210* Pragma Complex_Representation:: 1211* Pragma Component_Alignment:: 1212* Pragma Constant_After_Elaboration:: 1213* Pragma Contract_Cases:: 1214* Pragma Convention_Identifier:: 1215* Pragma CPP_Class:: 1216* Pragma CPP_Constructor:: 1217* Pragma CPP_Virtual:: 1218* Pragma CPP_Vtable:: 1219* Pragma CPU:: 1220* Pragma Deadline_Floor:: 1221* Pragma Default_Initial_Condition:: 1222* Pragma Debug:: 1223* Pragma Debug_Policy:: 1224* Pragma Default_Scalar_Storage_Order:: 1225* Pragma Default_Storage_Pool:: 1226* Pragma Depends:: 1227* Pragma Detect_Blocking:: 1228* Pragma Disable_Atomic_Synchronization:: 1229* Pragma Dispatching_Domain:: 1230* Pragma Effective_Reads:: 1231* Pragma Effective_Writes:: 1232* Pragma Elaboration_Checks:: 1233* Pragma Eliminate:: 1234* Pragma Enable_Atomic_Synchronization:: 1235* Pragma Export_Function:: 1236* Pragma Export_Object:: 1237* Pragma Export_Procedure:: 1238* Pragma Export_Value:: 1239* Pragma Export_Valued_Procedure:: 1240* Pragma Extend_System:: 1241* Pragma Extensions_Allowed:: 1242* Pragma Extensions_Visible:: 1243* Pragma External:: 1244* Pragma External_Name_Casing:: 1245* Pragma Fast_Math:: 1246* Pragma Favor_Top_Level:: 1247* Pragma Finalize_Storage_Only:: 1248* Pragma Float_Representation:: 1249* Pragma Ghost:: 1250* Pragma Global:: 1251* Pragma Ident:: 1252* Pragma Ignore_Pragma:: 1253* Pragma Implementation_Defined:: 1254* Pragma Implemented:: 1255* Pragma Implicit_Packing:: 1256* Pragma Import_Function:: 1257* Pragma Import_Object:: 1258* Pragma Import_Procedure:: 1259* Pragma Import_Valued_Procedure:: 1260* Pragma Independent:: 1261* Pragma Independent_Components:: 1262* Pragma Initial_Condition:: 1263* Pragma Initialize_Scalars:: 1264* Pragma Initializes:: 1265* Pragma Inline_Always:: 1266* Pragma Inline_Generic:: 1267* Pragma Interface:: 1268* Pragma Interface_Name:: 1269* Pragma Interrupt_Handler:: 1270* Pragma Interrupt_State:: 1271* Pragma Invariant:: 1272* Pragma Keep_Names:: 1273* Pragma License:: 1274* Pragma Link_With:: 1275* Pragma Linker_Alias:: 1276* Pragma Linker_Constructor:: 1277* Pragma Linker_Destructor:: 1278* Pragma Linker_Section:: 1279* Pragma Lock_Free:: 1280* Pragma Loop_Invariant:: 1281* Pragma Loop_Optimize:: 1282* Pragma Loop_Variant:: 1283* Pragma Machine_Attribute:: 1284* Pragma Main:: 1285* Pragma Main_Storage:: 1286* Pragma Max_Queue_Length:: 1287* Pragma No_Body:: 1288* Pragma No_Caching:: 1289* Pragma No_Component_Reordering:: 1290* Pragma No_Elaboration_Code_All:: 1291* Pragma No_Heap_Finalization:: 1292* Pragma No_Inline:: 1293* Pragma No_Return:: 1294* Pragma No_Strict_Aliasing:: 1295* Pragma No_Tagged_Streams:: 1296* Pragma Normalize_Scalars:: 1297* Pragma Obsolescent:: 1298* Pragma Optimize_Alignment:: 1299* Pragma Ordered:: 1300* Pragma Overflow_Mode:: 1301* Pragma Overriding_Renamings:: 1302* Pragma Partition_Elaboration_Policy:: 1303* Pragma Part_Of:: 1304* Pragma Passive:: 1305* Pragma Persistent_BSS:: 1306* Pragma Polling:: 1307* Pragma Post:: 1308* Pragma Postcondition:: 1309* Pragma Post_Class:: 1310* Pragma Rename_Pragma:: 1311* Pragma Pre:: 1312* Pragma Precondition:: 1313* Pragma Predicate:: 1314* Pragma Predicate_Failure:: 1315* Pragma Preelaborable_Initialization:: 1316* Pragma Prefix_Exception_Messages:: 1317* Pragma Pre_Class:: 1318* Pragma Priority_Specific_Dispatching:: 1319* Pragma Profile:: 1320* Pragma Profile_Warnings:: 1321* Pragma Propagate_Exceptions:: 1322* Pragma Provide_Shift_Operators:: 1323* Pragma Psect_Object:: 1324* Pragma Pure_Function:: 1325* Pragma Rational:: 1326* Pragma Ravenscar:: 1327* Pragma Refined_Depends:: 1328* Pragma Refined_Global:: 1329* Pragma Refined_Post:: 1330* Pragma Refined_State:: 1331* Pragma Relative_Deadline:: 1332* Pragma Remote_Access_Type:: 1333* Pragma Restricted_Run_Time:: 1334* Pragma Restriction_Warnings:: 1335* Pragma Reviewable:: 1336* Pragma Secondary_Stack_Size:: 1337* Pragma Share_Generic:: 1338* Pragma Shared:: 1339* Pragma Short_Circuit_And_Or:: 1340* Pragma Short_Descriptors:: 1341* Pragma Simple_Storage_Pool_Type:: 1342* Pragma Source_File_Name:: 1343* Pragma Source_File_Name_Project:: 1344* Pragma Source_Reference:: 1345* Pragma SPARK_Mode:: 1346* Pragma Static_Elaboration_Desired:: 1347* Pragma Stream_Convert:: 1348* Pragma Style_Checks:: 1349* Pragma Subtitle:: 1350* Pragma Suppress:: 1351* Pragma Suppress_All:: 1352* Pragma Suppress_Debug_Info:: 1353* Pragma Suppress_Exception_Locations:: 1354* Pragma Suppress_Initialization:: 1355* Pragma Task_Name:: 1356* Pragma Task_Storage:: 1357* Pragma Test_Case:: 1358* Pragma Thread_Local_Storage:: 1359* Pragma Time_Slice:: 1360* Pragma Title:: 1361* Pragma Type_Invariant:: 1362* Pragma Type_Invariant_Class:: 1363* Pragma Unchecked_Union:: 1364* Pragma Unevaluated_Use_Of_Old:: 1365* Pragma Unimplemented_Unit:: 1366* Pragma Universal_Aliasing:: 1367* Pragma Universal_Data:: 1368* Pragma Unmodified:: 1369* Pragma Unreferenced:: 1370* Pragma Unreferenced_Objects:: 1371* Pragma Unreserve_All_Interrupts:: 1372* Pragma Unsuppress:: 1373* Pragma Use_VADS_Size:: 1374* Pragma Unused:: 1375* Pragma Validity_Checks:: 1376* Pragma Volatile:: 1377* Pragma Volatile_Full_Access:: 1378* Pragma Volatile_Function:: 1379* Pragma Warning_As_Error:: 1380* Pragma Warnings:: 1381* Pragma Weak_External:: 1382* Pragma Wide_Character_Encoding:: 1383 1384@end menu 1385 1386@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1387@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b} 1388@section Pragma Abort_Defer 1389 1390 1391@geindex Deferring aborts 1392 1393Syntax: 1394 1395@example 1396pragma Abort_Defer; 1397@end example 1398 1399This pragma must appear at the start of the statement sequence of a 1400handled sequence of statements (right after the @code{begin}). It has 1401the effect of deferring aborts for the sequence of statements (but not 1402for the declarations or handlers, if any, associated with this statement 1403sequence). 1404 1405@node Pragma Abstract_State,Pragma Acc_Parallel,Pragma Abort_Defer,Implementation Defined Pragmas 1406@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d} 1407@section Pragma Abstract_State 1408 1409 1410Syntax: 1411 1412@example 1413pragma Abstract_State (ABSTRACT_STATE_LIST); 1414 1415ABSTRACT_STATE_LIST ::= 1416 null 1417 | STATE_NAME_WITH_OPTIONS 1418 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1419 1420STATE_NAME_WITH_OPTIONS ::= 1421 STATE_NAME 1422 | (STATE_NAME with OPTION_LIST) 1423 1424OPTION_LIST ::= OPTION @{, OPTION@} 1425 1426OPTION ::= 1427 SIMPLE_OPTION 1428 | NAME_VALUE_OPTION 1429 1430SIMPLE_OPTION ::= Ghost | Synchronous 1431 1432NAME_VALUE_OPTION ::= 1433 Part_Of => ABSTRACT_STATE 1434 | External [=> EXTERNAL_PROPERTY_LIST] 1435 1436EXTERNAL_PROPERTY_LIST ::= 1437 EXTERNAL_PROPERTY 1438 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1439 1440EXTERNAL_PROPERTY ::= 1441 Async_Readers [=> boolean_EXPRESSION] 1442 | Async_Writers [=> boolean_EXPRESSION] 1443 | Effective_Reads [=> boolean_EXPRESSION] 1444 | Effective_Writes [=> boolean_EXPRESSION] 1445 others => boolean_EXPRESSION 1446 1447STATE_NAME ::= defining_identifier 1448 1449ABSTRACT_STATE ::= name 1450@end example 1451 1452For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in 1453the SPARK 2014 Reference Manual, section 7.1.4. 1454 1455@node Pragma Acc_Parallel,Pragma Acc_Loop,Pragma Abstract_State,Implementation Defined Pragmas 1456@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-parallel}@anchor{1e} 1457@section Pragma Acc_Parallel 1458 1459 1460Syntax: 1461 1462@example 1463pragma Acc_Parallel [( ACC_PARALLEL_CLAUSE [, ACC_PARALLEL_CLAUSE... ])]; 1464 1465ACC_PARALLEL_CLAUSE ::= 1466 Acc_If => boolean_EXPRESSION 1467 | Acc_Private => IDENTIFIERS 1468 | Async => integer_EXPRESSION 1469 | Copy => IDENTIFIERS 1470 | Copy_In => IDENTIFIERS 1471 | Copy_Out => IDENTIFIERS 1472 | Create => IDENTIFIERS 1473 | Default => None 1474 | Device_Ptr => IDENTIFIERS 1475 | First_Private => IDENTIFIERS 1476 | Num_Gangs => integer_EXPRESSION 1477 | Num_Workers => integer_EXPRESSION 1478 | Present => IDENTIFIERS 1479 | Reduction => (REDUCTION_RECORD) 1480 | Vector_Length => integer_EXPRESSION 1481 | Wait => INTEGERS 1482 1483REDUCTION_RECORD ::= 1484 "+" => IDENTIFIERS 1485 | "*" => IDENTIFIERS 1486 | "min" => IDENTIFIERS 1487 | "max" => IDENTIFIERS 1488 | "or" => IDENTIFIERS 1489 | "and" => IDENTIFIERS 1490 1491IDENTIFIERS ::= 1492 | IDENTIFIER 1493 | (IDENTIFIER, IDENTIFIERS) 1494 1495INTEGERS ::= 1496 | integer_EXPRESSION 1497 | (integer_EXPRESSION, INTEGERS) 1498@end example 1499 1500Requires the @code{-fopenacc} flag. 1501 1502Equivalent to the @code{parallel} directive of the OpenAcc standard. This pragma 1503should be placed in loops. It offloads the content of the loop to an 1504accelerator device. 1505 1506For more information about the effect of the clauses, see the OpenAcc 1507specification. 1508 1509@node Pragma Acc_Loop,Pragma Acc_Kernels,Pragma Acc_Parallel,Implementation Defined Pragmas 1510@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-loop}@anchor{1f} 1511@section Pragma Acc_Loop 1512 1513 1514Syntax: 1515 1516@example 1517pragma Acc_Loop [( ACC_LOOP_CLAUSE [, ACC_LOOP_CLAUSE... ])]; 1518 1519ACC_LOOP_CLAUSE ::= 1520 Auto 1521 | Collapse => INTEGER_LITERAL 1522 | Gang [=> GANG_ARG] 1523 | Independent 1524 | Private => IDENTIFIERS 1525 | Reduction => (REDUCTION_RECORD) 1526 | Seq 1527 | Tile => SIZE_EXPRESSION 1528 | Vector [=> integer_EXPRESSION] 1529 | Worker [=> integer_EXPRESSION] 1530 1531GANG_ARG ::= 1532 integer_EXPRESSION 1533 | Static => SIZE_EXPRESSION 1534 1535SIZE_EXPRESSION ::= 1536 * 1537 | integer_EXPRESSION 1538@end example 1539 1540Requires the @code{-fopenacc} flag. 1541 1542Equivalent to the @code{loop} directive of the OpenAcc standard. This pragma 1543should be placed in for loops after the "Acc_Parallel" pragma. It tells the 1544compiler how to parallelize the loop. 1545 1546For more information about the effect of the clauses, see the OpenAcc 1547specification. 1548 1549@node Pragma Acc_Kernels,Pragma Acc_Data,Pragma Acc_Loop,Implementation Defined Pragmas 1550@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-kernels}@anchor{20} 1551@section Pragma Acc_Kernels 1552 1553 1554Syntax: 1555 1556@example 1557pragma Acc_Kernels [( ACC_KERNELS_CLAUSE [, ACC_KERNELS_CLAUSE...])]; 1558 1559ACC_KERNELS_CLAUSE ::= 1560 Acc_If => boolean_EXPRESSION 1561 | Async => integer_EXPRESSION 1562 | Copy => IDENTIFIERS 1563 | Copy_In => IDENTIFIERS 1564 | Copy_Out => IDENTIFIERS 1565 | Create => IDENTIFIERS 1566 | Default => None 1567 | Device_Ptr => IDENTIFIERS 1568 | Num_Gangs => integer_EXPRESSION 1569 | Num_Workers => integer_EXPRESSION 1570 | Present => IDENTIFIERS 1571 | Vector_Length => integer_EXPRESSION 1572 | Wait => INTEGERS 1573 1574IDENTIFIERS ::= 1575 | IDENTIFIER 1576 | (IDENTIFIER, IDENTIFIERS) 1577 1578INTEGERS ::= 1579 | integer_EXPRESSION 1580 | (integer_EXPRESSION, INTEGERS) 1581@end example 1582 1583Requires the @code{-fopenacc} flag. 1584 1585Equivalent to the kernels directive of the OpenAcc standard. This pragma should 1586be placed in loops. 1587 1588For more information about the effect of the clauses, see the OpenAcc 1589specification. 1590 1591@node Pragma Acc_Data,Pragma Ada_83,Pragma Acc_Kernels,Implementation Defined Pragmas 1592@anchor{gnat_rm/implementation_defined_pragmas pragma-acc-data}@anchor{21} 1593@section Pragma Acc_Data 1594 1595 1596Syntax: 1597 1598@example 1599pragma Acc_Data ([ ACC_DATA_CLAUSE [, ACC_DATA_CLAUSE...]]); 1600 1601ACC_DATA_CLAUSE ::= 1602 Copy => IDENTIFIERS 1603 | Copy_In => IDENTIFIERS 1604 | Copy_Out => IDENTIFIERS 1605 | Create => IDENTIFIERS 1606 | Device_Ptr => IDENTIFIERS 1607 | Present => IDENTIFIERS 1608@end example 1609 1610Requires the @code{-fopenacc} flag. 1611 1612Equivalent to the @code{data} directive of the OpenAcc standard. This pragma 1613should be placed in loops. 1614 1615For more information about the effect of the clauses, see the OpenAcc 1616specification. 1617 1618@node Pragma Ada_83,Pragma Ada_95,Pragma Acc_Data,Implementation Defined Pragmas 1619@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{22} 1620@section Pragma Ada_83 1621 1622 1623Syntax: 1624 1625@example 1626pragma Ada_83; 1627@end example 1628 1629A configuration pragma that establishes Ada 83 mode for the unit to 1630which it applies, regardless of the mode set by the command line 1631switches. In Ada 83 mode, GNAT attempts to be as compatible with 1632the syntax and semantics of Ada 83, as defined in the original Ada 163383 Reference Manual as possible. In particular, the keywords added by Ada 95 1634and Ada 2005 are not recognized, optional package bodies are allowed, 1635and generics may name types with unknown discriminants without using 1636the @code{(<>)} notation. In addition, some but not all of the additional 1637restrictions of Ada 83 are enforced. 1638 1639Ada 83 mode is intended for two purposes. Firstly, it allows existing 1640Ada 83 code to be compiled and adapted to GNAT with less effort. 1641Secondly, it aids in keeping code backwards compatible with Ada 83. 1642However, there is no guarantee that code that is processed correctly 1643by GNAT in Ada 83 mode will in fact compile and execute with an Ada 164483 compiler, since GNAT does not enforce all the additional checks 1645required by Ada 83. 1646 1647@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1648@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{23} 1649@section Pragma Ada_95 1650 1651 1652Syntax: 1653 1654@example 1655pragma Ada_95; 1656@end example 1657 1658A configuration pragma that establishes Ada 95 mode for the unit to which 1659it applies, regardless of the mode set by the command line switches. 1660This mode is set automatically for the @code{Ada} and @code{System} 1661packages and their children, so you need not specify it in these 1662contexts. This pragma is useful when writing a reusable component that 1663itself uses Ada 95 features, but which is intended to be usable from 1664either Ada 83 or Ada 95 programs. 1665 1666@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1667@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{24} 1668@section Pragma Ada_05 1669 1670 1671Syntax: 1672 1673@example 1674pragma Ada_05; 1675pragma Ada_05 (local_NAME); 1676@end example 1677 1678A configuration pragma that establishes Ada 2005 mode for the unit to which 1679it applies, regardless of the mode set by the command line switches. 1680This pragma is useful when writing a reusable component that 1681itself uses Ada 2005 features, but which is intended to be usable from 1682either Ada 83 or Ada 95 programs. 1683 1684The one argument form (which is not a configuration pragma) 1685is used for managing the transition from 1686Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1687as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1688mode will generate a warning. In addition, in Ada_83 or Ada_95 1689mode, a preference rule is established which does not choose 1690such an entity unless it is unambiguously specified. This avoids 1691extra subprograms marked this way from generating ambiguities in 1692otherwise legal pre-Ada_2005 programs. The one argument form is 1693intended for exclusive use in the GNAT run-time library. 1694 1695@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1696@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{25} 1697@section Pragma Ada_2005 1698 1699 1700Syntax: 1701 1702@example 1703pragma Ada_2005; 1704@end example 1705 1706This configuration pragma is a synonym for pragma Ada_05 and has the 1707same syntax and effect. 1708 1709@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1710@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{26} 1711@section Pragma Ada_12 1712 1713 1714Syntax: 1715 1716@example 1717pragma Ada_12; 1718pragma Ada_12 (local_NAME); 1719@end example 1720 1721A configuration pragma that establishes Ada 2012 mode for the unit to which 1722it applies, regardless of the mode set by the command line switches. 1723This mode is set automatically for the @code{Ada} and @code{System} 1724packages and their children, so you need not specify it in these 1725contexts. This pragma is useful when writing a reusable component that 1726itself uses Ada 2012 features, but which is intended to be usable from 1727Ada 83, Ada 95, or Ada 2005 programs. 1728 1729The one argument form, which is not a configuration pragma, 1730is used for managing the transition from Ada 17312005 to Ada 2012 in the run-time library. If an entity is marked 1732as Ada_2012 only, then referencing the entity in any pre-Ada_2012 1733mode will generate a warning. In addition, in any pre-Ada_2012 1734mode, a preference rule is established which does not choose 1735such an entity unless it is unambiguously specified. This avoids 1736extra subprograms marked this way from generating ambiguities in 1737otherwise legal pre-Ada_2012 programs. The one argument form is 1738intended for exclusive use in the GNAT run-time library. 1739 1740@node Pragma Ada_2012,Pragma Aggregate_Individually_Assign,Pragma Ada_12,Implementation Defined Pragmas 1741@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{27} 1742@section Pragma Ada_2012 1743 1744 1745Syntax: 1746 1747@example 1748pragma Ada_2012; 1749@end example 1750 1751This configuration pragma is a synonym for pragma Ada_12 and has the 1752same syntax and effect. 1753 1754@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas 1755@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{28} 1756@section Pragma Aggregate_Individually_Assign 1757 1758 1759Syntax: 1760 1761@example 1762pragma Aggregate_Individually_Assign; 1763@end example 1764 1765Where possible, GNAT will store the binary representation of a record aggregate 1766in memory for space and performance reasons. This configuration pragma changes 1767this behavior so that record aggregates are instead always converted into 1768individual assignment statements. 1769 1770@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas 1771@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{29} 1772@section Pragma Allow_Integer_Address 1773 1774 1775Syntax: 1776 1777@example 1778pragma Allow_Integer_Address; 1779@end example 1780 1781In almost all versions of GNAT, @code{System.Address} is a private 1782type in accordance with the implementation advice in the RM. This 1783means that integer values, 1784in particular integer literals, are not allowed as address values. 1785If the configuration pragma 1786@code{Allow_Integer_Address} is given, then integer expressions may 1787be used anywhere a value of type @code{System.Address} is required. 1788The effect is to introduce an implicit unchecked conversion from the 1789integer value to type @code{System.Address}. The reverse case of using 1790an address where an integer type is required is handled analogously. 1791The following example compiles without errors: 1792 1793@example 1794pragma Allow_Integer_Address; 1795with System; use System; 1796package AddrAsInt is 1797 X : Integer; 1798 Y : Integer; 1799 for X'Address use 16#1240#; 1800 for Y use at 16#3230#; 1801 m : Address := 16#4000#; 1802 n : constant Address := 4000; 1803 p : constant Address := Address (X + Y); 1804 v : Integer := y'Address; 1805 w : constant Integer := Integer (Y'Address); 1806 type R is new integer; 1807 RR : R := 1000; 1808 Z : Integer; 1809 for Z'Address use RR; 1810end AddrAsInt; 1811@end example 1812 1813Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} 1814is not a private type. In implementations of @code{GNAT} where 1815System.Address is a visible integer type, 1816this pragma serves no purpose but is ignored 1817rather than rejected to allow common sets of sources to be used 1818in the two situations. 1819 1820@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1821@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{2a}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{2b} 1822@section Pragma Annotate 1823 1824 1825Syntax: 1826 1827@example 1828pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1829 1830ARG ::= NAME | EXPRESSION 1831@end example 1832 1833This pragma is used to annotate programs. IDENTIFIER identifies 1834the type of annotation. GNAT verifies that it is an identifier, but does 1835not otherwise analyze it. The second optional identifier is also left 1836unanalyzed, and by convention is used to control the action of the tool to 1837which the annotation is addressed. The remaining ARG arguments 1838can be either string literals or more generally expressions. 1839String literals (and concatenations of string literals) are assumed to be 1840either of type 1841@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1842depending on the character literals they contain. 1843All other kinds of arguments are analyzed as expressions, and must be 1844unambiguous. The last argument if present must have the identifier 1845@code{Entity} and GNAT verifies that a local name is given. 1846 1847The analyzed pragma is retained in the tree, but not otherwise processed 1848by any part of the GNAT compiler, except to generate corresponding note 1849lines in the generated ALI file. For the format of these note lines, see 1850the compiler source file lib-writ.ads. This pragma is intended for use by 1851external tools, including ASIS. The use of pragma Annotate does not 1852affect the compilation process in any way. This pragma may be used as 1853a configuration pragma. 1854 1855@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1856@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2c} 1857@section Pragma Assert 1858 1859 1860Syntax: 1861 1862@example 1863pragma Assert ( 1864 boolean_EXPRESSION 1865 [, string_EXPRESSION]); 1866@end example 1867 1868The effect of this pragma depends on whether the corresponding command 1869line switch is set to activate assertions. The pragma expands into code 1870equivalent to the following: 1871 1872@example 1873if assertions-enabled then 1874 if not boolean_EXPRESSION then 1875 System.Assertions.Raise_Assert_Failure 1876 (string_EXPRESSION); 1877 end if; 1878end if; 1879@end example 1880 1881The string argument, if given, is the message that will be associated 1882with the exception occurrence if the exception is raised. If no second 1883argument is given, the default message is @code{file}:@code{nnn}, 1884where @code{file} is the name of the source file containing the assert, 1885and @code{nnn} is the line number of the assert. 1886 1887Note that, as with the @code{if} statement to which it is equivalent, the 1888type of the expression is either @code{Standard.Boolean}, or any type derived 1889from this standard type. 1890 1891Assert checks can be either checked or ignored. By default they are ignored. 1892They will be checked if either the command line switch @emph{-gnata} is 1893used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1894to enable @code{Assert_Checks}. 1895 1896If assertions are ignored, then there 1897is no run-time effect (and in particular, any side effects from the 1898expression will not occur at run time). (The expression is still 1899analyzed at compile time, and may cause types to be frozen if they are 1900mentioned here for the first time). 1901 1902If assertions are checked, then the given expression is tested, and if 1903it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1904which results in the raising of @code{Assert_Failure} with the given message. 1905 1906You should generally avoid side effects in the expression arguments of 1907this pragma, because these side effects will turn on and off with the 1908setting of the assertions mode, resulting in assertions that have an 1909effect on the program. However, the expressions are analyzed for 1910semantic correctness whether or not assertions are enabled, so turning 1911assertions on and off cannot affect the legality of a program. 1912 1913Note that the implementation defined policy @code{DISABLE}, given in a 1914pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1915 1916Note: this is a standard language-defined pragma in versions 1917of Ada from 2005 on. In GNAT, it is implemented in all versions 1918of Ada, and the DISABLE policy is an implementation-defined 1919addition. 1920 1921@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1922@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2d} 1923@section Pragma Assert_And_Cut 1924 1925 1926Syntax: 1927 1928@example 1929pragma Assert_And_Cut ( 1930 boolean_EXPRESSION 1931 [, string_EXPRESSION]); 1932@end example 1933 1934The effect of this pragma is identical to that of pragma @code{Assert}, 1935except that in an @code{Assertion_Policy} pragma, the identifier 1936@code{Assert_And_Cut} is used to control whether it is ignored or checked 1937(or disabled). 1938 1939The intention is that this be used within a subprogram when the 1940given test expresion sums up all the work done so far in the 1941subprogram, so that the rest of the subprogram can be verified 1942(informally or formally) using only the entry preconditions, 1943and the expression in this pragma. This allows dividing up 1944a subprogram into sections for the purposes of testing or 1945formal verification. The pragma also serves as useful 1946documentation. 1947 1948@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1949@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2e} 1950@section Pragma Assertion_Policy 1951 1952 1953Syntax: 1954 1955@example 1956pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); 1957 1958pragma Assertion_Policy ( 1959 ASSERTION_KIND => POLICY_IDENTIFIER 1960 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1961 1962ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1963 1964RM_ASSERTION_KIND ::= Assert | 1965 Static_Predicate | 1966 Dynamic_Predicate | 1967 Pre | 1968 Pre'Class | 1969 Post | 1970 Post'Class | 1971 Type_Invariant | 1972 Type_Invariant'Class 1973 1974ID_ASSERTION_KIND ::= Assertions | 1975 Assert_And_Cut | 1976 Assume | 1977 Contract_Cases | 1978 Debug | 1979 Ghost | 1980 Invariant | 1981 Invariant'Class | 1982 Loop_Invariant | 1983 Loop_Variant | 1984 Postcondition | 1985 Precondition | 1986 Predicate | 1987 Refined_Post | 1988 Statement_Assertions 1989 1990POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 1991@end example 1992 1993This is a standard Ada 2012 pragma that is available as an 1994implementation-defined pragma in earlier versions of Ada. 1995The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1996the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1997are implementation defined additions recognized by the GNAT compiler. 1998 1999The pragma applies in both cases to pragmas and aspects with matching 2000names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 2001applies to both the @code{Precondition} pragma 2002and the aspect @code{Precondition}. Note that the identifiers for 2003pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 2004Pre_Class and Post_Class), since these pragmas are intended to be 2005identical to the corresponding aspects). 2006 2007If the policy is @code{CHECK}, then assertions are enabled, i.e. 2008the corresponding pragma or aspect is activated. 2009If the policy is @code{IGNORE}, then assertions are ignored, i.e. 2010the corresponding pragma or aspect is deactivated. 2011This pragma overrides the effect of the @emph{-gnata} switch on the 2012command line. 2013If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, 2014however, if the @emph{-gnatp} switch is specified all assertions are ignored. 2015 2016The implementation defined policy @code{DISABLE} is like 2017@code{IGNORE} except that it completely disables semantic 2018checking of the corresponding pragma or aspect. This is 2019useful when the pragma or aspect argument references subprograms 2020in a with'ed package which is replaced by a dummy package 2021for the final build. 2022 2023The implementation defined assertion kind @code{Assertions} applies to all 2024assertion kinds. The form with no assertion kind given implies this 2025choice, so it applies to all assertion kinds (RM defined, and 2026implementation defined). 2027 2028The implementation defined assertion kind @code{Statement_Assertions} 2029applies to @code{Assert}, @code{Assert_And_Cut}, 2030@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 2031 2032@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 2033@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2f} 2034@section Pragma Assume 2035 2036 2037Syntax: 2038 2039@example 2040pragma Assume ( 2041 boolean_EXPRESSION 2042 [, string_EXPRESSION]); 2043@end example 2044 2045The effect of this pragma is identical to that of pragma @code{Assert}, 2046except that in an @code{Assertion_Policy} pragma, the identifier 2047@code{Assume} is used to control whether it is ignored or checked 2048(or disabled). 2049 2050The intention is that this be used for assumptions about the 2051external environment. So you cannot expect to verify formally 2052or informally that the condition is met, this must be 2053established by examining things outside the program itself. 2054For example, we may have code that depends on the size of 2055@code{Long_Long_Integer} being at least 64. So we could write: 2056 2057@example 2058pragma Assume (Long_Long_Integer'Size >= 64); 2059@end example 2060 2061This assumption cannot be proved from the program itself, 2062but it acts as a useful run-time check that the assumption 2063is met, and documents the need to ensure that it is met by 2064reference to information outside the program. 2065 2066@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 2067@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{30} 2068@section Pragma Assume_No_Invalid_Values 2069 2070 2071@geindex Invalid representations 2072 2073@geindex Invalid values 2074 2075Syntax: 2076 2077@example 2078pragma Assume_No_Invalid_Values (On | Off); 2079@end example 2080 2081This is a configuration pragma that controls the assumptions made by the 2082compiler about the occurrence of invalid representations (invalid values) 2083in the code. 2084 2085The default behavior (corresponding to an Off argument for this pragma), is 2086to assume that values may in general be invalid unless the compiler can 2087prove they are valid. Consider the following example: 2088 2089@example 2090V1 : Integer range 1 .. 10; 2091V2 : Integer range 11 .. 20; 2092... 2093for J in V2 .. V1 loop 2094 ... 2095end loop; 2096@end example 2097 2098if V1 and V2 have valid values, then the loop is known at compile 2099time not to execute since the lower bound must be greater than the 2100upper bound. However in default mode, no such assumption is made, 2101and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 2102is given, the compiler will assume that any occurrence of a variable 2103other than in an explicit @code{'Valid} test always has a valid 2104value, and the loop above will be optimized away. 2105 2106The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 2107you know your code is free of uninitialized variables and other 2108possible sources of invalid representations, and may result in 2109more efficient code. A program that accesses an invalid representation 2110with this pragma in effect is erroneous, so no guarantees can be made 2111about its behavior. 2112 2113It is peculiar though permissible to use this pragma in conjunction 2114with validity checking (-gnatVa). In such cases, accessing invalid 2115values will generally give an exception, though formally the program 2116is erroneous so there are no guarantees that this will always be the 2117case, and it is recommended that these two options not be used together. 2118 2119@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 2120@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{32} 2121@section Pragma Async_Readers 2122 2123 2124Syntax: 2125 2126@example 2127pragma Async_Readers [ (boolean_EXPRESSION) ]; 2128@end example 2129 2130For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in 2131the SPARK 2014 Reference Manual, section 7.1.2. 2132 2133@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 2134@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{33}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{34} 2135@section Pragma Async_Writers 2136 2137 2138Syntax: 2139 2140@example 2141pragma Async_Writers [ (boolean_EXPRESSION) ]; 2142@end example 2143 2144For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in 2145the SPARK 2014 Reference Manual, section 7.1.2. 2146 2147@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 2148@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{35} 2149@section Pragma Attribute_Definition 2150 2151 2152Syntax: 2153 2154@example 2155pragma Attribute_Definition 2156 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 2157 [Entity =>] LOCAL_NAME, 2158 [Expression =>] EXPRESSION | NAME); 2159@end example 2160 2161If @code{Attribute} is a known attribute name, this pragma is equivalent to 2162the attribute definition clause: 2163 2164@example 2165for Entity'Attribute use Expression; 2166@end example 2167 2168If @code{Attribute} is not a recognized attribute name, the pragma is 2169ignored, and a warning is emitted. This allows source 2170code to be written that takes advantage of some new attribute, while remaining 2171compilable with earlier compilers. 2172 2173@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 2174@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{36} 2175@section Pragma C_Pass_By_Copy 2176 2177 2178@geindex Passing by copy 2179 2180Syntax: 2181 2182@example 2183pragma C_Pass_By_Copy 2184 ([Max_Size =>] static_integer_EXPRESSION); 2185@end example 2186 2187Normally the default mechanism for passing C convention records to C 2188convention subprograms is to pass them by reference, as suggested by RM 2189B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 2190this default, by requiring that record formal parameters be passed by 2191copy if all of the following conditions are met: 2192 2193 2194@itemize * 2195 2196@item 2197The size of the record type does not exceed the value specified for 2198@code{Max_Size}. 2199 2200@item 2201The record type has @code{Convention C}. 2202 2203@item 2204The formal parameter has this record type, and the subprogram has a 2205foreign (non-Ada) convention. 2206@end itemize 2207 2208If these conditions are met the argument is passed by copy; i.e., in a 2209manner consistent with what C expects if the corresponding formal in the 2210C prototype is a struct (rather than a pointer to a struct). 2211 2212You can also pass records by copy by specifying the convention 2213@code{C_Pass_By_Copy} for the record type, or by using the extended 2214@code{Import} and @code{Export} pragmas, which allow specification of 2215passing mechanisms on a parameter by parameter basis. 2216 2217@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 2218@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{37} 2219@section Pragma Check 2220 2221 2222@geindex Assertions 2223 2224@geindex Named assertions 2225 2226Syntax: 2227 2228@example 2229pragma Check ( 2230 [Name =>] CHECK_KIND, 2231 [Check =>] Boolean_EXPRESSION 2232 [, [Message =>] string_EXPRESSION] ); 2233 2234CHECK_KIND ::= IDENTIFIER | 2235 Pre'Class | 2236 Post'Class | 2237 Type_Invariant'Class | 2238 Invariant'Class 2239@end example 2240 2241This pragma is similar to the predefined pragma @code{Assert} except that an 2242extra identifier argument is present. In conjunction with pragma 2243@code{Check_Policy}, this can be used to define groups of assertions that can 2244be independently controlled. The identifier @code{Assertion} is special, it 2245refers to the normal set of pragma @code{Assert} statements. 2246 2247Checks introduced by this pragma are normally deactivated by default. They can 2248be activated either by the command line option @emph{-gnata}, which turns on 2249all checks, or individually controlled using pragma @code{Check_Policy}. 2250 2251The identifiers @code{Assertions} and @code{Statement_Assertions} are not 2252permitted as check kinds, since this would cause confusion with the use 2253of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 2254pragmas, where they are used to refer to sets of assertions. 2255 2256@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2257@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{38} 2258@section Pragma Check_Float_Overflow 2259 2260 2261@geindex Floating-point overflow 2262 2263Syntax: 2264 2265@example 2266pragma Check_Float_Overflow; 2267@end example 2268 2269In Ada, the predefined floating-point types (@code{Short_Float}, 2270@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 2271defined to be @emph{unconstrained}. This means that even though each 2272has a well-defined base range, an operation that delivers a result 2273outside this base range is not required to raise an exception. 2274This implementation permission accommodates the notion 2275of infinities in IEEE floating-point, and corresponds to the 2276efficient execution mode on most machines. GNAT will not raise 2277overflow exceptions on these machines; instead it will generate 2278infinities and NaN's as defined in the IEEE standard. 2279 2280Generating infinities, although efficient, is not always desirable. 2281Often the preferable approach is to check for overflow, even at the 2282(perhaps considerable) expense of run-time performance. 2283This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 2284range constraints -- and indeed such a subtype 2285can have the same base range as its base type. For example: 2286 2287@example 2288subtype My_Float is Float range Float'Range; 2289@end example 2290 2291Here @code{My_Float} has the same range as 2292@code{Float} but is constrained, so operations on 2293@code{My_Float} values will be checked for overflow 2294against this range. 2295 2296This style will achieve the desired goal, but 2297it is often more convenient to be able to simply use 2298the standard predefined floating-point types as long 2299as overflow checking could be guaranteed. 2300The @code{Check_Float_Overflow} 2301configuration pragma achieves this effect. If a unit is compiled 2302subject to this configuration pragma, then all operations 2303on predefined floating-point types including operations on 2304base types of these floating-point types will be treated as 2305though those types were constrained, and overflow checks 2306will be generated. The @code{Constraint_Error} 2307exception is raised if the result is out of range. 2308 2309This mode can also be set by use of the compiler 2310switch @emph{-gnateF}. 2311 2312@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2313@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{39} 2314@section Pragma Check_Name 2315 2316 2317@geindex Defining check names 2318 2319@geindex Check names 2320@geindex defining 2321 2322Syntax: 2323 2324@example 2325pragma Check_Name (check_name_IDENTIFIER); 2326@end example 2327 2328This is a configuration pragma that defines a new implementation 2329defined check name (unless IDENTIFIER matches one of the predefined 2330check names, in which case the pragma has no effect). Check names 2331are global to a partition, so if two or more configuration pragmas 2332are present in a partition mentioning the same name, only one new 2333check name is introduced. 2334 2335An implementation defined check name introduced with this pragma may 2336be used in only three contexts: @code{pragma Suppress}, 2337@code{pragma Unsuppress}, 2338and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 2339any of these three cases, the check name must be visible. A check 2340name is visible if it is in the configuration pragmas applying to 2341the current unit, or if it appears at the start of any unit that 2342is part of the dependency set of the current unit (e.g., units that 2343are mentioned in @code{with} clauses). 2344 2345Check names introduced by this pragma are subject to control by compiler 2346switches (in particular -gnatp) in the usual manner. 2347 2348@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2349@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{3a} 2350@section Pragma Check_Policy 2351 2352 2353@geindex Controlling assertions 2354 2355@geindex Assertions 2356@geindex control 2357 2358@geindex Check pragma control 2359 2360@geindex Named assertions 2361 2362Syntax: 2363 2364@example 2365pragma Check_Policy 2366 ([Name =>] CHECK_KIND, 2367 [Policy =>] POLICY_IDENTIFIER); 2368 2369pragma Check_Policy ( 2370 CHECK_KIND => POLICY_IDENTIFIER 2371 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2372 2373ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2374 2375CHECK_KIND ::= IDENTIFIER | 2376 Pre'Class | 2377 Post'Class | 2378 Type_Invariant'Class | 2379 Invariant'Class 2380 2381The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2382avoids confusion between the two possible syntax forms for this pragma. 2383 2384POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2385@end example 2386 2387This pragma is used to set the checking policy for assertions (specified 2388by aspects or pragmas), the @code{Debug} pragma, or additional checks 2389to be checked using the @code{Check} pragma. It may appear either as 2390a configuration pragma, or within a declarative part of package. In the 2391latter case, it applies from the point where it appears to the end of 2392the declarative region (like pragma @code{Suppress}). 2393 2394The @code{Check_Policy} pragma is similar to the 2395predefined @code{Assertion_Policy} pragma, 2396and if the check kind corresponds to one of the assertion kinds that 2397are allowed by @code{Assertion_Policy}, then the effect is identical. 2398 2399If the first argument is Debug, then the policy applies to Debug pragmas, 2400disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 2401@code{IGNORE}, and allowing them to execute with normal semantics if 2402the policy is @code{ON} or @code{CHECK}. In addition if the policy is 2403@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 2404be totally ignored and not analyzed semantically. 2405 2406Finally the first argument may be some other identifier than the above 2407possibilities, in which case it controls a set of named assertions 2408that can be checked using pragma @code{Check}. For example, if the pragma: 2409 2410@example 2411pragma Check_Policy (Critical_Error, OFF); 2412@end example 2413 2414is given, then subsequent @code{Check} pragmas whose first argument is also 2415@code{Critical_Error} will be disabled. 2416 2417The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 2418to turn on corresponding checks. The default for a set of checks for which no 2419@code{Check_Policy} is given is @code{OFF} unless the compiler switch 2420@emph{-gnata} is given, which turns on all checks by default. 2421 2422The check policy settings @code{CHECK} and @code{IGNORE} are recognized 2423as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 2424compatibility with the standard @code{Assertion_Policy} pragma. The check 2425policy setting @code{DISABLE} causes the second argument of a corresponding 2426@code{Check} pragma to be completely ignored and not analyzed. 2427 2428@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2429@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{3b} 2430@section Pragma Comment 2431 2432 2433Syntax: 2434 2435@example 2436pragma Comment (static_string_EXPRESSION); 2437@end example 2438 2439This is almost identical in effect to pragma @code{Ident}. It allows the 2440placement of a comment into the object file and hence into the 2441executable file if the operating system permits such usage. The 2442difference is that @code{Comment}, unlike @code{Ident}, has 2443no limitations on placement of the pragma (it can be placed 2444anywhere in the main source unit), and if more than one pragma 2445is used, all comments are retained. 2446 2447@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2448@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3c} 2449@section Pragma Common_Object 2450 2451 2452Syntax: 2453 2454@example 2455pragma Common_Object ( 2456 [Internal =>] LOCAL_NAME 2457 [, [External =>] EXTERNAL_SYMBOL] 2458 [, [Size =>] EXTERNAL_SYMBOL] ); 2459 2460EXTERNAL_SYMBOL ::= 2461 IDENTIFIER 2462| static_string_EXPRESSION 2463@end example 2464 2465This pragma enables the shared use of variables stored in overlaid 2466linker areas corresponding to the use of @code{COMMON} 2467in Fortran. The single 2468object @code{LOCAL_NAME} is assigned to the area designated by 2469the @code{External} argument. 2470You may define a record to correspond to a series 2471of fields. The @code{Size} argument 2472is syntax checked in GNAT, but otherwise ignored. 2473 2474@code{Common_Object} is not supported on all platforms. If no 2475support is available, then the code generator will issue a message 2476indicating that the necessary attribute for implementation of this 2477pragma is not available. 2478 2479@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2480@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3d} 2481@section Pragma Compile_Time_Error 2482 2483 2484Syntax: 2485 2486@example 2487pragma Compile_Time_Error 2488 (boolean_EXPRESSION, static_string_EXPRESSION); 2489@end example 2490 2491This pragma can be used to generate additional compile time 2492error messages. It 2493is particularly useful in generics, where errors can be issued for 2494specific problematic instantiations. The first parameter is a boolean 2495expression. The pragma is effective only if the value of this expression 2496is known at compile time, and has the value True. The set of expressions 2497whose values are known at compile time includes all static boolean 2498expressions, and also other values which the compiler can determine 2499at compile time (e.g., the size of a record type set by an explicit 2500size representation clause, or the value of a variable which was 2501initialized to a constant and is known not to have been modified). 2502If these conditions are met, an error message is generated using 2503the value given as the second argument. This string value may contain 2504embedded ASCII.LF characters to break the message into multiple lines. 2505 2506@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2507@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3e} 2508@section Pragma Compile_Time_Warning 2509 2510 2511Syntax: 2512 2513@example 2514pragma Compile_Time_Warning 2515 (boolean_EXPRESSION, static_string_EXPRESSION); 2516@end example 2517 2518Same as pragma Compile_Time_Error, except a warning is issued instead 2519of an error message. Note that if this pragma is used in a package that 2520is with'ed by a client, the client will get the warning even though it 2521is issued by a with'ed package (normally warnings in with'ed units are 2522suppressed, but this is a special exception to that rule). 2523 2524One typical use is within a generic where compile time known characteristics 2525of formal parameters are tested, and warnings given appropriately. Another use 2526with a first parameter of True is to warn a client about use of a package, 2527for example that it is not fully implemented. 2528 2529@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2530@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3f} 2531@section Pragma Compiler_Unit 2532 2533 2534Syntax: 2535 2536@example 2537pragma Compiler_Unit; 2538@end example 2539 2540This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2541retained so that old versions of the GNAT run-time that use this pragma can 2542be compiled with newer versions of the compiler. 2543 2544@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2545@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{40} 2546@section Pragma Compiler_Unit_Warning 2547 2548 2549Syntax: 2550 2551@example 2552pragma Compiler_Unit_Warning; 2553@end example 2554 2555This pragma is intended only for internal use in the GNAT run-time library. 2556It indicates that the unit is used as part of the compiler build. The effect 2557is to generate warnings for the use of constructs (for example, conditional 2558expressions) that would cause trouble when bootstrapping using an older 2559version of GNAT. For the exact list of restrictions, see the compiler sources 2560and references to Check_Compiler_Unit. 2561 2562@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2563@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{41} 2564@section Pragma Complete_Representation 2565 2566 2567Syntax: 2568 2569@example 2570pragma Complete_Representation; 2571@end example 2572 2573This pragma must appear immediately within a record representation 2574clause. Typical placements are before the first component clause 2575or after the last component clause. The effect is to give an error 2576message if any component is missing a component clause. This pragma 2577may be used to ensure that a record representation clause is 2578complete, and that this invariant is maintained if fields are 2579added to the record in the future. 2580 2581@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2582@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{42} 2583@section Pragma Complex_Representation 2584 2585 2586Syntax: 2587 2588@example 2589pragma Complex_Representation 2590 ([Entity =>] LOCAL_NAME); 2591@end example 2592 2593The @code{Entity} argument must be the name of a record type which has 2594two fields of the same floating-point type. The effect of this pragma is 2595to force gcc to use the special internal complex representation form for 2596this record, which may be more efficient. Note that this may result in 2597the code for this type not conforming to standard ABI (application 2598binary interface) requirements for the handling of record types. For 2599example, in some environments, there is a requirement for passing 2600records by pointer, and the use of this pragma may result in passing 2601this type in floating-point registers. 2602 2603@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2604@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{43} 2605@section Pragma Component_Alignment 2606 2607 2608@geindex Alignments of components 2609 2610@geindex Pragma Component_Alignment 2611 2612Syntax: 2613 2614@example 2615pragma Component_Alignment ( 2616 [Form =>] ALIGNMENT_CHOICE 2617 [, [Name =>] type_LOCAL_NAME]); 2618 2619ALIGNMENT_CHOICE ::= 2620 Component_Size 2621| Component_Size_4 2622| Storage_Unit 2623| Default 2624@end example 2625 2626Specifies the alignment of components in array or record types. 2627The meaning of the @code{Form} argument is as follows: 2628 2629@quotation 2630 2631@geindex Component_Size (in pragma Component_Alignment) 2632@end quotation 2633 2634 2635@table @asis 2636 2637@item @emph{Component_Size} 2638 2639Aligns scalar components and subcomponents of the array or record type 2640on boundaries appropriate to their inherent size (naturally 2641aligned). For example, 1-byte components are aligned on byte boundaries, 26422-byte integer components are aligned on 2-byte boundaries, 4-byte 2643integer components are aligned on 4-byte boundaries and so on. These 2644alignment rules correspond to the normal rules for C compilers on all 2645machines except the VAX. 2646 2647@geindex Component_Size_4 (in pragma Component_Alignment) 2648 2649@item @emph{Component_Size_4} 2650 2651Naturally aligns components with a size of four or fewer 2652bytes. Components that are larger than 4 bytes are placed on the next 26534-byte boundary. 2654 2655@geindex Storage_Unit (in pragma Component_Alignment) 2656 2657@item @emph{Storage_Unit} 2658 2659Specifies that array or record components are byte aligned, i.e., 2660aligned on boundaries determined by the value of the constant 2661@code{System.Storage_Unit}. 2662 2663@geindex Default (in pragma Component_Alignment) 2664 2665@item @emph{Default} 2666 2667Specifies that array or record components are aligned on default 2668boundaries, appropriate to the underlying hardware or operating system or 2669both. The @code{Default} choice is the same as @code{Component_Size} (natural 2670alignment). 2671@end table 2672 2673If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must 2674refer to a local record or array type, and the specified alignment 2675choice applies to the specified type. The use of 2676@code{Component_Alignment} together with a pragma @code{Pack} causes the 2677@code{Component_Alignment} pragma to be ignored. The use of 2678@code{Component_Alignment} together with a record representation clause 2679is only effective for fields not specified by the representation clause. 2680 2681If the @code{Name} parameter is absent, the pragma can be used as either 2682a configuration pragma, in which case it applies to one or more units in 2683accordance with the normal rules for configuration pragmas, or it can be 2684used within a declarative part, in which case it applies to types that 2685are declared within this declarative part, or within any nested scope 2686within this declarative part. In either case it specifies the alignment 2687to be applied to any record or array type which has otherwise standard 2688representation. 2689 2690If the alignment for a record or array type is not specified (using 2691pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2692clause), the GNAT uses the default alignment as described previously. 2693 2694@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2695@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{44}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{45} 2696@section Pragma Constant_After_Elaboration 2697 2698 2699Syntax: 2700 2701@example 2702pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2703@end example 2704 2705For the semantics of this pragma, see the entry for aspect 2706@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2707 2708@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2709@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{46}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{47} 2710@section Pragma Contract_Cases 2711 2712 2713@geindex Contract cases 2714 2715Syntax: 2716 2717@example 2718pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2719 2720CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2721 2722CASE_GUARD ::= boolean_EXPRESSION | others 2723 2724CONSEQUENCE ::= boolean_EXPRESSION 2725@end example 2726 2727The @code{Contract_Cases} pragma allows defining fine-grain specifications 2728that can complement or replace the contract given by a precondition and a 2729postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2730by testing and formal verification tools. The compiler checks its validity and, 2731depending on the assertion policy at the point of declaration of the pragma, 2732it may insert a check in the executable. For code generation, the contract 2733cases 2734 2735@example 2736pragma Contract_Cases ( 2737 Cond1 => Pred1, 2738 Cond2 => Pred2); 2739@end example 2740 2741are equivalent to 2742 2743@example 2744C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2745C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2746pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2747pragma Postcondition (if C1 then Pred1); 2748pragma Postcondition (if C2 then Pred2); 2749@end example 2750 2751The precondition ensures that one and only one of the case guards is 2752satisfied on entry to the subprogram. 2753The postcondition ensures that for the case guard that was True on entry, 2754the corresponding consequence is True on exit. Other consequence expressions 2755are not evaluated. 2756 2757A precondition @code{P} and postcondition @code{Q} can also be 2758expressed as contract cases: 2759 2760@example 2761pragma Contract_Cases (P => Q); 2762@end example 2763 2764The placement and visibility rules for @code{Contract_Cases} pragmas are 2765identical to those described for preconditions and postconditions. 2766 2767The compiler checks that boolean expressions given in case guards and 2768consequences are valid, where the rules for case guards are the same as 2769the rule for an expression in @code{Precondition} and the rules for 2770consequences are the same as the rule for an expression in 2771@code{Postcondition}. In particular, attributes @code{'Old} and 2772@code{'Result} can only be used within consequence expressions. 2773The case guard for the last contract case may be @code{others}, to denote 2774any case not captured by the previous cases. The 2775following is an example of use within a package spec: 2776 2777@example 2778package Math_Functions is 2779 ... 2780 function Sqrt (Arg : Float) return Float; 2781 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 2782 Arg >= 100.0 => Sqrt'Result >= 10.0, 2783 others => Sqrt'Result = 0.0)); 2784 ... 2785end Math_Functions; 2786@end example 2787 2788The meaning of contract cases is that only one case should apply at each 2789call, as determined by the corresponding case guard evaluating to True, 2790and that the consequence for this case should hold when the subprogram 2791returns. 2792 2793@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2794@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{48} 2795@section Pragma Convention_Identifier 2796 2797 2798@geindex Conventions 2799@geindex synonyms 2800 2801Syntax: 2802 2803@example 2804pragma Convention_Identifier ( 2805 [Name =>] IDENTIFIER, 2806 [Convention =>] convention_IDENTIFIER); 2807@end example 2808 2809This pragma provides a mechanism for supplying synonyms for existing 2810convention identifiers. The @code{Name} identifier can subsequently 2811be used as a synonym for the given convention in other pragmas (including 2812for example pragma @code{Import} or another @code{Convention_Identifier} 2813pragma). As an example of the use of this, suppose you had legacy code 2814which used Fortran77 as the identifier for Fortran. Then the pragma: 2815 2816@example 2817pragma Convention_Identifier (Fortran77, Fortran); 2818@end example 2819 2820would allow the use of the convention identifier @code{Fortran77} in 2821subsequent code, avoiding the need to modify the sources. As another 2822example, you could use this to parameterize convention requirements 2823according to systems. Suppose you needed to use @code{Stdcall} on 2824windows systems, and @code{C} on some other system, then you could 2825define a convention identifier @code{Library} and use a single 2826@code{Convention_Identifier} pragma to specify which convention 2827would be used system-wide. 2828 2829@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2830@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{49} 2831@section Pragma CPP_Class 2832 2833 2834@geindex Interfacing with C++ 2835 2836Syntax: 2837 2838@example 2839pragma CPP_Class ([Entity =>] LOCAL_NAME); 2840@end example 2841 2842The argument denotes an entity in the current declarative region that is 2843declared as a record type. It indicates that the type corresponds to an 2844externally declared C++ class type, and is to be laid out the same way 2845that C++ would lay out the type. If the C++ class has virtual primitives 2846then the record must be declared as a tagged record type. 2847 2848Types for which @code{CPP_Class} is specified do not have assignment or 2849equality operators defined (such operations can be imported or declared 2850as subprograms as required). Initialization is allowed only by constructor 2851functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2852limited if not explicitly declared as limited or derived from a limited 2853type, and an error is issued in that case. 2854 2855See @ref{4a,,Interfacing to C++} for related information. 2856 2857Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2858for backward compatibility but its functionality is available 2859using pragma @code{Import} with @code{Convention} = @code{CPP}. 2860 2861@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2862@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{4b} 2863@section Pragma CPP_Constructor 2864 2865 2866@geindex Interfacing with C++ 2867 2868Syntax: 2869 2870@example 2871pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2872 [, [External_Name =>] static_string_EXPRESSION ] 2873 [, [Link_Name =>] static_string_EXPRESSION ]); 2874@end example 2875 2876This pragma identifies an imported function (imported in the usual way 2877with pragma @code{Import}) as corresponding to a C++ constructor. If 2878@code{External_Name} and @code{Link_Name} are not specified then the 2879@code{Entity} argument is a name that must have been previously mentioned 2880in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2881must be of one of the following forms: 2882 2883 2884@itemize * 2885 2886@item 2887@strong{function} @code{Fname} @strong{return} T` 2888 2889@item 2890@strong{function} @code{Fname} @strong{return} T'Class 2891 2892@item 2893@strong{function} @code{Fname} (...) @strong{return} T` 2894 2895@item 2896@strong{function} @code{Fname} (...) @strong{return} T'Class 2897@end itemize 2898 2899where @code{T} is a limited record type imported from C++ with pragma 2900@code{Import} and @code{Convention} = @code{CPP}. 2901 2902The first two forms import the default constructor, used when an object 2903of type @code{T} is created on the Ada side with no explicit constructor. 2904The latter two forms cover all the non-default constructors of the type. 2905See the GNAT User's Guide for details. 2906 2907If no constructors are imported, it is impossible to create any objects 2908on the Ada side and the type is implicitly declared abstract. 2909 2910Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2911using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2912GCC switch). 2913See @ref{4a,,Interfacing to C++} for more related information. 2914 2915Note: The use of functions returning class-wide types for constructors is 2916currently obsolete. They are supported for backward compatibility. The 2917use of functions returning the type T leave the Ada sources more clear 2918because the imported C++ constructors always return an object of type T; 2919that is, they never return an object whose type is a descendant of type T. 2920 2921@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2922@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{4c} 2923@section Pragma CPP_Virtual 2924 2925 2926@geindex Interfacing to C++ 2927 2928This pragma is now obsolete and, other than generating a warning if warnings 2929on obsolescent features are enabled, is completely ignored. 2930It is retained for compatibility 2931purposes. It used to be required to ensure compoatibility with C++, but 2932is no longer required for that purpose because GNAT generates 2933the same object layout as the G++ compiler by default. 2934 2935See @ref{4a,,Interfacing to C++} for related information. 2936 2937@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2938@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4d} 2939@section Pragma CPP_Vtable 2940 2941 2942@geindex Interfacing with C++ 2943 2944This pragma is now obsolete and, other than generating a warning if warnings 2945on obsolescent features are enabled, is completely ignored. 2946It used to be required to ensure compatibility with C++, but 2947is no longer required for that purpose because GNAT generates 2948the same object layout as the G++ compiler by default. 2949 2950See @ref{4a,,Interfacing to C++} for related information. 2951 2952@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas 2953@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4e} 2954@section Pragma CPU 2955 2956 2957Syntax: 2958 2959@example 2960pragma CPU (EXPRESSION); 2961@end example 2962 2963This pragma is standard in Ada 2012, but is available in all earlier 2964versions of Ada as an implementation-defined pragma. 2965See Ada 2012 Reference Manual for details. 2966 2967@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas 2968@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4f} 2969@section Pragma Deadline_Floor 2970 2971 2972Syntax: 2973 2974@example 2975pragma Deadline_Floor (time_span_EXPRESSION); 2976@end example 2977 2978This pragma applies only to protected types and specifies the floor 2979deadline inherited by a task when the task enters a protected object. 2980It is effective only when the EDF scheduling policy is used. 2981 2982@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas 2983@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{50}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{51} 2984@section Pragma Default_Initial_Condition 2985 2986 2987Syntax: 2988 2989@example 2990pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2991@end example 2992 2993For the semantics of this pragma, see the entry for aspect 2994@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2995 2996@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2997@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{52} 2998@section Pragma Debug 2999 3000 3001Syntax: 3002 3003@example 3004pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 3005 3006PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 3007 PROCEDURE_NAME 3008| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 3009@end example 3010 3011The procedure call argument has the syntactic form of an expression, meeting 3012the syntactic requirements for pragmas. 3013 3014If debug pragmas are not enabled or if the condition is present and evaluates 3015to False, this pragma has no effect. If debug pragmas are enabled, the 3016semantics of the pragma is exactly equivalent to the procedure call statement 3017corresponding to the argument with a terminating semicolon. Pragmas are 3018permitted in sequences of declarations, so you can use pragma @code{Debug} to 3019intersperse calls to debug procedures in the middle of declarations. Debug 3020pragmas can be enabled either by use of the command line switch @emph{-gnata} 3021or by use of the pragma @code{Check_Policy} with a first argument of 3022@code{Debug}. 3023 3024@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 3025@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{53} 3026@section Pragma Debug_Policy 3027 3028 3029Syntax: 3030 3031@example 3032pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 3033@end example 3034 3035This pragma is equivalent to a corresponding @code{Check_Policy} pragma 3036with a first argument of @code{Debug}. It is retained for historical 3037compatibility reasons. 3038 3039@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 3040@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{54} 3041@section Pragma Default_Scalar_Storage_Order 3042 3043 3044@geindex Default_Scalar_Storage_Order 3045 3046@geindex Scalar_Storage_Order 3047 3048Syntax: 3049 3050@example 3051pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 3052@end example 3053 3054Normally if no explicit @code{Scalar_Storage_Order} is given for a record 3055type or array type, then the scalar storage order defaults to the ordinary 3056default for the target. But this default may be overridden using this pragma. 3057The pragma may appear as a configuration pragma, or locally within a package 3058spec or declarative part. In the latter case, it applies to all subsequent 3059types declared within that package spec or declarative part. 3060 3061The following example shows the use of this pragma: 3062 3063@example 3064pragma Default_Scalar_Storage_Order (High_Order_First); 3065with System; use System; 3066package DSSO1 is 3067 type H1 is record 3068 a : Integer; 3069 end record; 3070 3071 type L2 is record 3072 a : Integer; 3073 end record; 3074 for L2'Scalar_Storage_Order use Low_Order_First; 3075 3076 type L2a is new L2; 3077 3078 package Inner is 3079 type H3 is record 3080 a : Integer; 3081 end record; 3082 3083 pragma Default_Scalar_Storage_Order (Low_Order_First); 3084 3085 type L4 is record 3086 a : Integer; 3087 end record; 3088 end Inner; 3089 3090 type H4a is new Inner.L4; 3091 3092 type H5 is record 3093 a : Integer; 3094 end record; 3095end DSSO1; 3096@end example 3097 3098In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar 3099storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. 3100Note that in the case of @code{H4a}, the order is not inherited 3101from the parent type. Only an explicitly set @code{Scalar_Storage_Order} 3102gets inherited on type derivation. 3103 3104If this pragma is used as a configuration pragma which appears within a 3105configuration pragma file (as opposed to appearing explicitly at the start 3106of a single unit), then the binder will require that all units in a partition 3107be compiled in a similar manner, other than run-time units, which are not 3108affected by this pragma. Note that the use of this form is discouraged because 3109it may significantly degrade the run-time performance of the software, instead 3110the default scalar storage order ought to be changed only on a local basis. 3111 3112@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 3113@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{55} 3114@section Pragma Default_Storage_Pool 3115 3116 3117@geindex Default_Storage_Pool 3118 3119Syntax: 3120 3121@example 3122pragma Default_Storage_Pool (storage_pool_NAME | null); 3123@end example 3124 3125This pragma is standard in Ada 2012, but is available in all earlier 3126versions of Ada as an implementation-defined pragma. 3127See Ada 2012 Reference Manual for details. 3128 3129@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 3130@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{56}@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{57} 3131@section Pragma Depends 3132 3133 3134Syntax: 3135 3136@example 3137pragma Depends (DEPENDENCY_RELATION); 3138 3139DEPENDENCY_RELATION ::= 3140 null 3141 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 3142 3143DEPENDENCY_CLAUSE ::= 3144 OUTPUT_LIST =>[+] INPUT_LIST 3145 | NULL_DEPENDENCY_CLAUSE 3146 3147NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 3148 3149OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 3150 3151INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 3152 3153OUTPUT ::= NAME | FUNCTION_RESULT 3154INPUT ::= NAME 3155 3156where FUNCTION_RESULT is a function Result attribute_reference 3157@end example 3158 3159For the semantics of this pragma, see the entry for aspect @code{Depends} in the 3160SPARK 2014 Reference Manual, section 6.1.5. 3161 3162@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 3163@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{58} 3164@section Pragma Detect_Blocking 3165 3166 3167Syntax: 3168 3169@example 3170pragma Detect_Blocking; 3171@end example 3172 3173This is a standard pragma in Ada 2005, that is available in all earlier 3174versions of Ada as an implementation-defined pragma. 3175 3176This is a configuration pragma that forces the detection of potentially 3177blocking operations within a protected operation, and to raise Program_Error 3178if that happens. 3179 3180@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 3181@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{59} 3182@section Pragma Disable_Atomic_Synchronization 3183 3184 3185@geindex Atomic Synchronization 3186 3187Syntax: 3188 3189@example 3190pragma Disable_Atomic_Synchronization [(Entity)]; 3191@end example 3192 3193Ada requires that accesses (reads or writes) of an atomic variable be 3194regarded as synchronization points in the case of multiple tasks. 3195Particularly in the case of multi-processors this may require special 3196handling, e.g. the generation of memory barriers. This capability may 3197be turned off using this pragma in cases where it is known not to be 3198required. 3199 3200The placement and scope rules for this pragma are the same as those 3201for @code{pragma Suppress}. In particular it can be used as a 3202configuration pragma, or in a declaration sequence where it applies 3203till the end of the scope. If an @code{Entity} argument is present, 3204the action applies only to that entity. 3205 3206@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 3207@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{5a} 3208@section Pragma Dispatching_Domain 3209 3210 3211Syntax: 3212 3213@example 3214pragma Dispatching_Domain (EXPRESSION); 3215@end example 3216 3217This pragma is standard in Ada 2012, but is available in all earlier 3218versions of Ada as an implementation-defined pragma. 3219See Ada 2012 Reference Manual for details. 3220 3221@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 3222@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{5b}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5c} 3223@section Pragma Effective_Reads 3224 3225 3226Syntax: 3227 3228@example 3229pragma Effective_Reads [ (boolean_EXPRESSION) ]; 3230@end example 3231 3232For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in 3233the SPARK 2014 Reference Manual, section 7.1.2. 3234 3235@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3236@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5d}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5e} 3237@section Pragma Effective_Writes 3238 3239 3240Syntax: 3241 3242@example 3243pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3244@end example 3245 3246For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} 3247in the SPARK 2014 Reference Manual, section 7.1.2. 3248 3249@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3250@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5f} 3251@section Pragma Elaboration_Checks 3252 3253 3254@geindex Elaboration control 3255 3256Syntax: 3257 3258@example 3259pragma Elaboration_Checks (Dynamic | Static); 3260@end example 3261 3262This is a configuration pragma which specifies the elaboration model to be 3263used during compilation. For more information on the elaboration models of 3264GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User's 3265Guide}. 3266 3267The pragma may appear in the following contexts: 3268 3269 3270@itemize * 3271 3272@item 3273Configuration pragmas file 3274 3275@item 3276Prior to the context clauses of a compilation unit's initial declaration 3277@end itemize 3278 3279Any other placement of the pragma will result in a warning and the effects of 3280the offending pragma will be ignored. 3281 3282If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in 3283effect. If the pragma argument is @code{Static}, then the static elaboration model 3284is in effect. 3285 3286@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3287@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{60} 3288@section Pragma Eliminate 3289 3290 3291@geindex Elimination of unused subprograms 3292 3293Syntax: 3294 3295@example 3296pragma Eliminate ( 3297 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 3298 [ Entity => ] IDENTIFIER | 3299 SELECTED_COMPONENT | 3300 STRING_LITERAL 3301 [, Source_Location => SOURCE_TRACE ] ); 3302 3303 SOURCE_TRACE ::= STRING_LITERAL 3304@end example 3305 3306This pragma indicates that the given entity is not used in the program to be 3307compiled and built, thus allowing the compiler to 3308eliminate the code or data associated with the named entity. Any reference to 3309an eliminated entity causes a compile-time or link-time error. 3310 3311The pragma has the following semantics, where @code{U} is the unit specified by 3312the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} 3313argument: 3314 3315 3316@itemize * 3317 3318@item 3319@code{E} must be a subprogram that is explicitly declared either: 3320 3321o Within @code{U}, or 3322 3323o Within a generic package that is instantiated in @code{U}, or 3324 3325o As an instance of generic subprogram instantiated in @code{U}. 3326 3327Otherwise the pragma is ignored. 3328 3329@item 3330If @code{E} is overloaded within @code{U} then, in the absence of a 3331@code{Source_Location} argument, all overloadings are eliminated. 3332 3333@item 3334If @code{E} is overloaded within @code{U} and only some overloadings 3335are to be eliminated, then each overloading to be eliminated 3336must be specified in a corresponding pragma @code{Eliminate} 3337with a @code{Source_Location} argument identifying the line where the 3338declaration appears, as described below. 3339 3340@item 3341If @code{E} is declared as the result of a generic instantiation, then 3342a @code{Source_Location} argument is needed, as described below 3343@end itemize 3344 3345Pragma @code{Eliminate} allows a program to be compiled in a system-independent 3346manner, so that unused entities are eliminated but without 3347needing to modify the source text. Normally the required set of 3348@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. 3349 3350Any source file change that removes, splits, or 3351adds lines may make the set of @code{Eliminate} pragmas invalid because their 3352@code{Source_Location} argument values may get out of date. 3353 3354Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 3355operation. In this case all the subprograms to which the given operation can 3356dispatch are considered to be unused (are never called as a result of a direct 3357or a dispatching call). 3358 3359The string literal given for the source location specifies the line number 3360of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: 3361 3362@example 3363SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 3364 3365LBRACKET ::= '[' 3366RBRACKET ::= ']' 3367 3368SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3369 3370LINE_NUMBER ::= DIGIT @{DIGIT@} 3371@end example 3372 3373Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. 3374 3375The source trace that is given as the @code{Source_Location} must obey the 3376following rules (or else the pragma is ignored), where @code{U} is 3377the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the 3378subprogram specified by the @code{Entity} argument: 3379 3380 3381@itemize * 3382 3383@item 3384@code{FILE_NAME} is the short name (with no directory 3385information) of the Ada source file for @code{U}, using the required syntax 3386for the underlying file system (e.g. case is significant if the underlying 3387operating system is case sensitive). 3388If @code{U} is a package and @code{E} is a subprogram declared in the package 3389specification and its full declaration appears in the package body, 3390then the relevant source file is the one for the package specification; 3391analogously if @code{U} is a generic package. 3392 3393@item 3394If @code{E} is not declared in a generic instantiation (this includes 3395generic subprogram instances), the source trace includes only one source 3396line reference. @code{LINE_NUMBER} gives the line number of the occurrence 3397of the declaration of @code{E} within the source file (as a decimal literal 3398without an exponent or point). 3399 3400@item 3401If @code{E} is declared by a generic instantiation, its source trace 3402(from left to right) starts with the source location of the 3403declaration of @code{E} in the generic unit and ends with the source 3404location of the instantiation, given in square brackets. This approach is 3405applied recursively with nested instantiations: the rightmost (nested 3406most deeply in square brackets) element of the source trace is the location 3407of the outermost instantiation, and the leftmost element (that is, outside 3408of any square brackets) is the location of the declaration of @code{E} in 3409the generic unit. 3410@end itemize 3411 3412Examples: 3413 3414@quotation 3415 3416@example 3417pragma Eliminate (Pkg0, Proc); 3418-- Eliminate (all overloadings of) Proc in Pkg0 3419 3420pragma Eliminate (Pkg1, Proc, 3421 Source_Location => "pkg1.ads:8"); 3422-- Eliminate overloading of Proc at line 8 in pkg1.ads 3423 3424-- Assume the following file contents: 3425-- gen_pkg.ads 3426-- 1: generic 3427-- 2: type T is private; 3428-- 3: package Gen_Pkg is 3429-- 4: procedure Proc(N : T); 3430-- ... ... 3431-- ... end Gen_Pkg; 3432-- 3433-- q.adb 3434-- 1: with Gen_Pkg; 3435-- 2: procedure Q is 3436-- 3: package Inst_Pkg is new Gen_Pkg(Integer); 3437-- ... -- No calls on Inst_Pkg.Proc 3438-- ... end Q; 3439 3440-- The following pragma eliminates Inst_Pkg.Proc from Q 3441pragma Eliminate (Q, Proc, 3442 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 3443@end example 3444@end quotation 3445 3446@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3447@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{61} 3448@section Pragma Enable_Atomic_Synchronization 3449 3450 3451@geindex Atomic Synchronization 3452 3453Syntax: 3454 3455@example 3456pragma Enable_Atomic_Synchronization [(Entity)]; 3457@end example 3458 3459Ada requires that accesses (reads or writes) of an atomic variable be 3460regarded as synchronization points in the case of multiple tasks. 3461Particularly in the case of multi-processors this may require special 3462handling, e.g. the generation of memory barriers. This synchronization 3463is performed by default, but can be turned off using 3464@code{pragma Disable_Atomic_Synchronization}. The 3465@code{Enable_Atomic_Synchronization} pragma can be used to turn 3466it back on. 3467 3468The placement and scope rules for this pragma are the same as those 3469for @code{pragma Unsuppress}. In particular it can be used as a 3470configuration pragma, or in a declaration sequence where it applies 3471till the end of the scope. If an @code{Entity} argument is present, 3472the action applies only to that entity. 3473 3474@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3475@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{62} 3476@section Pragma Export_Function 3477 3478 3479@geindex Argument passing mechanisms 3480 3481Syntax: 3482 3483@example 3484pragma Export_Function ( 3485 [Internal =>] LOCAL_NAME 3486 [, [External =>] EXTERNAL_SYMBOL] 3487 [, [Parameter_Types =>] PARAMETER_TYPES] 3488 [, [Result_Type =>] result_SUBTYPE_MARK] 3489 [, [Mechanism =>] MECHANISM] 3490 [, [Result_Mechanism =>] MECHANISM_NAME]); 3491 3492EXTERNAL_SYMBOL ::= 3493 IDENTIFIER 3494| static_string_EXPRESSION 3495| "" 3496 3497PARAMETER_TYPES ::= 3498 null 3499| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3500 3501TYPE_DESIGNATOR ::= 3502 subtype_NAME 3503| subtype_Name ' Access 3504 3505MECHANISM ::= 3506 MECHANISM_NAME 3507| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3508 3509MECHANISM_ASSOCIATION ::= 3510 [formal_parameter_NAME =>] MECHANISM_NAME 3511 3512MECHANISM_NAME ::= Value | Reference 3513@end example 3514 3515Use this pragma to make a function externally callable and optionally 3516provide information on mechanisms to be used for passing parameter and 3517result values. We recommend, for the purposes of improving portability, 3518this pragma always be used in conjunction with a separate pragma 3519@code{Export}, which must precede the pragma @code{Export_Function}. 3520GNAT does not require a separate pragma @code{Export}, but if none is 3521present, @code{Convention Ada} is assumed, which is usually 3522not what is wanted, so it is usually appropriate to use this 3523pragma in conjunction with a @code{Export} or @code{Convention} 3524pragma that specifies the desired foreign convention. 3525Pragma @code{Export_Function} 3526(and @code{Export}, if present) must appear in the same declarative 3527region as the function to which they apply. 3528 3529The @code{internal_name} must uniquely designate the function to which the 3530pragma applies. If more than one function name exists of this name in 3531the declarative part you must use the @code{Parameter_Types} and 3532@code{Result_Type} parameters to achieve the required 3533unique designation. The @cite{subtype_mark}s in these parameters must 3534exactly match the subtypes in the corresponding function specification, 3535using positional notation to match parameters with subtype marks. 3536The form with an @code{'Access} attribute can be used to match an 3537anonymous access parameter. 3538 3539@geindex Suppressing external name 3540 3541Special treatment is given if the EXTERNAL is an explicit null 3542string or a static string expressions that evaluates to the null 3543string. In this case, no external name is generated. This form 3544still allows the specification of parameter mechanisms. 3545 3546@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3547@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{63} 3548@section Pragma Export_Object 3549 3550 3551Syntax: 3552 3553@example 3554pragma Export_Object 3555 [Internal =>] LOCAL_NAME 3556 [, [External =>] EXTERNAL_SYMBOL] 3557 [, [Size =>] EXTERNAL_SYMBOL] 3558 3559EXTERNAL_SYMBOL ::= 3560 IDENTIFIER 3561| static_string_EXPRESSION 3562@end example 3563 3564This pragma designates an object as exported, and apart from the 3565extended rules for external symbols, is identical in effect to the use of 3566the normal @code{Export} pragma applied to an object. You may use a 3567separate Export pragma (and you probably should from the point of view 3568of portability), but it is not required. @code{Size} is syntax checked, 3569but otherwise ignored by GNAT. 3570 3571@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas 3572@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{64} 3573@section Pragma Export_Procedure 3574 3575 3576Syntax: 3577 3578@example 3579pragma Export_Procedure ( 3580 [Internal =>] LOCAL_NAME 3581 [, [External =>] EXTERNAL_SYMBOL] 3582 [, [Parameter_Types =>] PARAMETER_TYPES] 3583 [, [Mechanism =>] MECHANISM]); 3584 3585EXTERNAL_SYMBOL ::= 3586 IDENTIFIER 3587| static_string_EXPRESSION 3588| "" 3589 3590PARAMETER_TYPES ::= 3591 null 3592| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3593 3594TYPE_DESIGNATOR ::= 3595 subtype_NAME 3596| subtype_Name ' Access 3597 3598MECHANISM ::= 3599 MECHANISM_NAME 3600| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3601 3602MECHANISM_ASSOCIATION ::= 3603 [formal_parameter_NAME =>] MECHANISM_NAME 3604 3605MECHANISM_NAME ::= Value | Reference 3606@end example 3607 3608This pragma is identical to @code{Export_Function} except that it 3609applies to a procedure rather than a function and the parameters 3610@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3611GNAT does not require a separate pragma @code{Export}, but if none is 3612present, @code{Convention Ada} is assumed, which is usually 3613not what is wanted, so it is usually appropriate to use this 3614pragma in conjunction with a @code{Export} or @code{Convention} 3615pragma that specifies the desired foreign convention. 3616 3617@geindex Suppressing external name 3618 3619Special treatment is given if the EXTERNAL is an explicit null 3620string or a static string expressions that evaluates to the null 3621string. In this case, no external name is generated. This form 3622still allows the specification of parameter mechanisms. 3623 3624@node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas 3625@anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{65} 3626@section Pragma Export_Value 3627 3628 3629Syntax: 3630 3631@example 3632pragma Export_Value ( 3633 [Value =>] static_integer_EXPRESSION, 3634 [Link_Name =>] static_string_EXPRESSION); 3635@end example 3636 3637This pragma serves to export a static integer value for external use. 3638The first argument specifies the value to be exported. The Link_Name 3639argument specifies the symbolic name to be associated with the integer 3640value. This pragma is useful for defining a named static value in Ada 3641that can be referenced in assembly language units to be linked with 3642the application. This pragma is currently supported only for the 3643AAMP target and is ignored for other targets. 3644 3645@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas 3646@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{66} 3647@section Pragma Export_Valued_Procedure 3648 3649 3650Syntax: 3651 3652@example 3653pragma Export_Valued_Procedure ( 3654 [Internal =>] LOCAL_NAME 3655 [, [External =>] EXTERNAL_SYMBOL] 3656 [, [Parameter_Types =>] PARAMETER_TYPES] 3657 [, [Mechanism =>] MECHANISM]); 3658 3659EXTERNAL_SYMBOL ::= 3660 IDENTIFIER 3661| static_string_EXPRESSION 3662| "" 3663 3664PARAMETER_TYPES ::= 3665 null 3666| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3667 3668TYPE_DESIGNATOR ::= 3669 subtype_NAME 3670| subtype_Name ' Access 3671 3672MECHANISM ::= 3673 MECHANISM_NAME 3674| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3675 3676MECHANISM_ASSOCIATION ::= 3677 [formal_parameter_NAME =>] MECHANISM_NAME 3678 3679MECHANISM_NAME ::= Value | Reference 3680@end example 3681 3682This pragma is identical to @code{Export_Procedure} except that the 3683first parameter of @code{LOCAL_NAME}, which must be present, must be of 3684mode @code{out}, and externally the subprogram is treated as a function 3685with this parameter as the result of the function. GNAT provides for 3686this capability to allow the use of @code{out} and @code{in out} 3687parameters in interfacing to external functions (which are not permitted 3688in Ada functions). 3689GNAT does not require a separate pragma @code{Export}, but if none is 3690present, @code{Convention Ada} is assumed, which is almost certainly 3691not what is wanted since the whole point of this pragma is to interface 3692with foreign language functions, so it is usually appropriate to use this 3693pragma in conjunction with a @code{Export} or @code{Convention} 3694pragma that specifies the desired foreign convention. 3695 3696@geindex Suppressing external name 3697 3698Special treatment is given if the EXTERNAL is an explicit null 3699string or a static string expressions that evaluates to the null 3700string. In this case, no external name is generated. This form 3701still allows the specification of parameter mechanisms. 3702 3703@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3704@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{67} 3705@section Pragma Extend_System 3706 3707 3708@geindex System 3709@geindex extending 3710 3711@geindex DEC Ada 83 3712 3713Syntax: 3714 3715@example 3716pragma Extend_System ([Name =>] IDENTIFIER); 3717@end example 3718 3719This pragma is used to provide backwards compatibility with other 3720implementations that extend the facilities of package @code{System}. In 3721GNAT, @code{System} contains only the definitions that are present in 3722the Ada RM. However, other implementations, notably the DEC Ada 83 3723implementation, provide many extensions to package @code{System}. 3724 3725For each such implementation accommodated by this pragma, GNAT provides a 3726package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 3727implementation, which provides the required additional definitions. You 3728can use this package in two ways. You can @code{with} it in the normal 3729way and access entities either by selection or using a @code{use} 3730clause. In this case no special processing is required. 3731 3732However, if existing code contains references such as 3733@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended 3734definitions provided in package @code{System}, you may use this pragma 3735to extend visibility in @code{System} in a non-standard way that 3736provides greater compatibility with the existing code. Pragma 3737@code{Extend_System} is a configuration pragma whose single argument is 3738the name of the package containing the extended definition 3739(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3740control of this pragma will be processed using special visibility 3741processing that looks in package @code{System.Aux_@emph{xxx}} where 3742@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in 3743package @code{System}, but not found in package @code{System}. 3744 3745You can use this pragma either to access a predefined @code{System} 3746extension supplied with the compiler, for example @code{Aux_DEC} or 3747you can construct your own extension unit following the above 3748definition. Note that such a package is a child of @code{System} 3749and thus is considered part of the implementation. 3750To compile it you will have to use the @emph{-gnatg} switch 3751for compiling System units, as explained in the 3752GNAT User's Guide. 3753 3754@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3755@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{68} 3756@section Pragma Extensions_Allowed 3757 3758 3759@geindex Ada Extensions 3760 3761@geindex GNAT Extensions 3762 3763Syntax: 3764 3765@example 3766pragma Extensions_Allowed (On | Off); 3767@end example 3768 3769This configuration pragma enables or disables the implementation 3770extension mode (the use of Off as a parameter cancels the effect 3771of the @emph{-gnatX} command switch). 3772 3773In extension mode, the latest version of the Ada language is 3774implemented (currently Ada 2012), and in addition a small number 3775of GNAT specific extensions are recognized as follows: 3776 3777 3778@table @asis 3779 3780@item @emph{Constrained attribute for generic objects} 3781 3782The @code{Constrained} attribute is permitted for objects of 3783generic types. The result indicates if the corresponding actual 3784is constrained. 3785@end table 3786 3787@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3788@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{69}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{6a} 3789@section Pragma Extensions_Visible 3790 3791 3792Syntax: 3793 3794@example 3795pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3796@end example 3797 3798For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} 3799in the SPARK 2014 Reference Manual, section 6.1.7. 3800 3801@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3802@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6b} 3803@section Pragma External 3804 3805 3806Syntax: 3807 3808@example 3809pragma External ( 3810 [ Convention =>] convention_IDENTIFIER, 3811 [ Entity =>] LOCAL_NAME 3812 [, [External_Name =>] static_string_EXPRESSION ] 3813 [, [Link_Name =>] static_string_EXPRESSION ]); 3814@end example 3815 3816This pragma is identical in syntax and semantics to pragma 3817@code{Export} as defined in the Ada Reference Manual. It is 3818provided for compatibility with some Ada 83 compilers that 3819used this pragma for exactly the same purposes as pragma 3820@code{Export} before the latter was standardized. 3821 3822@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3823@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6c} 3824@section Pragma External_Name_Casing 3825 3826 3827@geindex Dec Ada 83 casing compatibility 3828 3829@geindex External Names 3830@geindex casing 3831 3832@geindex Casing of External names 3833 3834Syntax: 3835 3836@example 3837pragma External_Name_Casing ( 3838 Uppercase | Lowercase 3839 [, Uppercase | Lowercase | As_Is]); 3840@end example 3841 3842This pragma provides control over the casing of external names associated 3843with Import and Export pragmas. There are two cases to consider: 3844 3845 3846@itemize * 3847 3848@item 3849Implicit external names 3850 3851Implicit external names are derived from identifiers. The most common case 3852arises when a standard Ada Import or Export pragma is used with only two 3853arguments, as in: 3854 3855@example 3856pragma Import (C, C_Routine); 3857@end example 3858 3859Since Ada is a case-insensitive language, the spelling of the identifier in 3860the Ada source program does not provide any information on the desired 3861casing of the external name, and so a convention is needed. In GNAT the 3862default treatment is that such names are converted to all lower case 3863letters. This corresponds to the normal C style in many environments. 3864The first argument of pragma @code{External_Name_Casing} can be used to 3865control this treatment. If @code{Uppercase} is specified, then the name 3866will be forced to all uppercase letters. If @code{Lowercase} is specified, 3867then the normal default of all lower case letters will be used. 3868 3869This same implicit treatment is also used in the case of extended DEC Ada 83 3870compatible Import and Export pragmas where an external name is explicitly 3871specified using an identifier rather than a string. 3872 3873@item 3874Explicit external names 3875 3876Explicit external names are given as string literals. The most common case 3877arises when a standard Ada Import or Export pragma is used with three 3878arguments, as in: 3879 3880@example 3881pragma Import (C, C_Routine, "C_routine"); 3882@end example 3883 3884In this case, the string literal normally provides the exact casing required 3885for the external name. The second argument of pragma 3886@code{External_Name_Casing} may be used to modify this behavior. 3887If @code{Uppercase} is specified, then the name 3888will be forced to all uppercase letters. If @code{Lowercase} is specified, 3889then the name will be forced to all lowercase letters. A specification of 3890@code{As_Is} provides the normal default behavior in which the casing is 3891taken from the string provided. 3892@end itemize 3893 3894This pragma may appear anywhere that a pragma is valid. In particular, it 3895can be used as a configuration pragma in the @code{gnat.adc} file, in which 3896case it applies to all subsequent compilations, or it can be used as a program 3897unit pragma, in which case it only applies to the current unit, or it can 3898be used more locally to control individual Import/Export pragmas. 3899 3900It was primarily intended for use with OpenVMS systems, where many 3901compilers convert all symbols to upper case by default. For interfacing to 3902such compilers (e.g., the DEC C compiler), it may be convenient to use 3903the pragma: 3904 3905@example 3906pragma External_Name_Casing (Uppercase, Uppercase); 3907@end example 3908 3909to enforce the upper casing of all external symbols. 3910 3911@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 3912@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6d} 3913@section Pragma Fast_Math 3914 3915 3916Syntax: 3917 3918@example 3919pragma Fast_Math; 3920@end example 3921 3922This is a configuration pragma which activates a mode in which speed is 3923considered more important for floating-point operations than absolutely 3924accurate adherence to the requirements of the standard. Currently the 3925following operations are affected: 3926 3927 3928@table @asis 3929 3930@item @emph{Complex Multiplication} 3931 3932The normal simple formula for complex multiplication can result in intermediate 3933overflows for numbers near the end of the range. The Ada standard requires that 3934this situation be detected and corrected by scaling, but in Fast_Math mode such 3935cases will simply result in overflow. Note that to take advantage of this you 3936must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 3937under control of the pragma, rather than use the preinstantiated versions. 3938@end table 3939 3940@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 3941@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6f} 3942@section Pragma Favor_Top_Level 3943 3944 3945Syntax: 3946 3947@example 3948pragma Favor_Top_Level (type_NAME); 3949@end example 3950 3951The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram 3952type. This pragma is an efficiency hint to the compiler, regarding the use of 3953@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. 3954The pragma means that nested subprograms are not used with this type, or are 3955rare, so that the generated code should be efficient in the top-level case. 3956When this pragma is used, dynamically generated trampolines may be used on some 3957targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. 3958 3959@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 3960@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{70} 3961@section Pragma Finalize_Storage_Only 3962 3963 3964Syntax: 3965 3966@example 3967pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3968@end example 3969 3970The argument of pragma @code{Finalize_Storage_Only} must denote a local type which 3971is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The 3972pragma suppresses the call to @code{Finalize} for declared library-level objects 3973of the argument type. This is mostly useful for types where finalization is 3974only used to deal with storage reclamation since in most environments it is 3975not necessary to reclaim memory just before terminating execution, hence the 3976name. Note that this pragma does not suppress Finalize calls for library-level 3977heap-allocated objects (see pragma @code{No_Heap_Finalization}). 3978 3979@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 3980@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{71} 3981@section Pragma Float_Representation 3982 3983 3984Syntax: 3985 3986@example 3987pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3988 3989FLOAT_REP ::= VAX_Float | IEEE_Float 3990@end example 3991 3992In the one argument form, this pragma is a configuration pragma which 3993allows control over the internal representation chosen for the predefined 3994floating point types declared in the packages @code{Standard} and 3995@code{System}. This pragma is only provided for compatibility and has no effect. 3996 3997The two argument form specifies the representation to be used for 3998the specified floating-point type. The argument must 3999be @code{IEEE_Float} to specify the use of IEEE format, as follows: 4000 4001 4002@itemize * 4003 4004@item 4005For a digits value of 6, 32-bit IEEE short format will be used. 4006 4007@item 4008For a digits value of 15, 64-bit IEEE long format will be used. 4009 4010@item 4011No other value of digits is permitted. 4012@end itemize 4013 4014@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 4015@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{72}@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{73} 4016@section Pragma Ghost 4017 4018 4019Syntax: 4020 4021@example 4022pragma Ghost [ (boolean_EXPRESSION) ]; 4023@end example 4024 4025For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK 40262014 Reference Manual, section 6.9. 4027 4028@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 4029@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{74}@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{75} 4030@section Pragma Global 4031 4032 4033Syntax: 4034 4035@example 4036pragma Global (GLOBAL_SPECIFICATION); 4037 4038GLOBAL_SPECIFICATION ::= 4039 null 4040 | (GLOBAL_LIST) 4041 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 4042 4043MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 4044 4045MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 4046GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 4047GLOBAL_ITEM ::= NAME 4048@end example 4049 4050For the semantics of this pragma, see the entry for aspect @code{Global} in the 4051SPARK 2014 Reference Manual, section 6.1.4. 4052 4053@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 4054@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{76} 4055@section Pragma Ident 4056 4057 4058Syntax: 4059 4060@example 4061pragma Ident (static_string_EXPRESSION); 4062@end example 4063 4064This pragma is identical in effect to pragma @code{Comment}. It is provided 4065for compatibility with other Ada compilers providing this pragma. 4066 4067@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 4068@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{77} 4069@section Pragma Ignore_Pragma 4070 4071 4072Syntax: 4073 4074@example 4075pragma Ignore_Pragma (pragma_IDENTIFIER); 4076@end example 4077 4078This is a configuration pragma 4079that takes a single argument that is a simple identifier. Any subsequent 4080use of a pragma whose pragma identifier matches this argument will be 4081silently ignored. This may be useful when legacy code or code intended 4082for compilation with some other compiler contains pragmas that match the 4083name, but not the exact implementation, of a GNAT pragma. The use of this 4084pragma allows such pragmas to be ignored, which may be useful in CodePeer 4085mode, or during porting of legacy code. 4086 4087@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 4088@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{78} 4089@section Pragma Implementation_Defined 4090 4091 4092Syntax: 4093 4094@example 4095pragma Implementation_Defined (local_NAME); 4096@end example 4097 4098This pragma marks a previously declared entity as implementation-defined. 4099For an overloaded entity, applies to the most recent homonym. 4100 4101@example 4102pragma Implementation_Defined; 4103@end example 4104 4105The form with no arguments appears anywhere within a scope, most 4106typically a package spec, and indicates that all entities that are 4107defined within the package spec are Implementation_Defined. 4108 4109This pragma is used within the GNAT runtime library to identify 4110implementation-defined entities introduced in language-defined units, 4111for the purpose of implementing the No_Implementation_Identifiers 4112restriction. 4113 4114@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 4115@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{79} 4116@section Pragma Implemented 4117 4118 4119Syntax: 4120 4121@example 4122pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 4123 4124implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 4125@end example 4126 4127This is an Ada 2012 representation pragma which applies to protected, task 4128and synchronized interface primitives. The use of pragma Implemented provides 4129a way to impose a static requirement on the overriding operation by adhering 4130to one of the three implementation kinds: entry, protected procedure or any of 4131the above. This pragma is available in all earlier versions of Ada as an 4132implementation-defined pragma. 4133 4134@example 4135type Synch_Iface is synchronized interface; 4136procedure Prim_Op (Obj : in out Iface) is abstract; 4137pragma Implemented (Prim_Op, By_Protected_Procedure); 4138 4139protected type Prot_1 is new Synch_Iface with 4140 procedure Prim_Op; -- Legal 4141end Prot_1; 4142 4143protected type Prot_2 is new Synch_Iface with 4144 entry Prim_Op; -- Illegal 4145end Prot_2; 4146 4147task type Task_Typ is new Synch_Iface with 4148 entry Prim_Op; -- Illegal 4149end Task_Typ; 4150@end example 4151 4152When applied to the procedure_or_entry_NAME of a requeue statement, pragma 4153Implemented determines the runtime behavior of the requeue. Implementation kind 4154By_Entry guarantees that the action of requeueing will proceed from an entry to 4155another entry. Implementation kind By_Protected_Procedure transforms the 4156requeue into a dispatching call, thus eliminating the chance of blocking. Kind 4157By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 4158the target's overriding subprogram kind. 4159 4160@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 4161@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{7a} 4162@section Pragma Implicit_Packing 4163 4164 4165@geindex Rational Profile 4166 4167Syntax: 4168 4169@example 4170pragma Implicit_Packing; 4171@end example 4172 4173This is a configuration pragma that requests implicit packing for packed 4174arrays for which a size clause is given but no explicit pragma Pack or 4175specification of Component_Size is present. It also applies to records 4176where no record representation clause is present. Consider this example: 4177 4178@example 4179type R is array (0 .. 7) of Boolean; 4180for R'Size use 8; 4181@end example 4182 4183In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 4184does not change the layout of a composite object. So the Size clause in the 4185above example is normally rejected, since the default layout of the array uses 41868-bit components, and thus the array requires a minimum of 64 bits. 4187 4188If this declaration is compiled in a region of code covered by an occurrence 4189of the configuration pragma Implicit_Packing, then the Size clause in this 4190and similar examples will cause implicit packing and thus be accepted. For 4191this implicit packing to occur, the type in question must be an array of small 4192components whose size is known at compile time, and the Size clause must 4193specify the exact size that corresponds to the number of elements in the array 4194multiplied by the size in bits of the component type (both single and 4195multi-dimensioned arrays can be controlled with this pragma). 4196 4197@geindex Array packing 4198 4199Similarly, the following example shows the use in the record case 4200 4201@example 4202type r is record 4203 a, b, c, d, e, f, g, h : boolean; 4204 chr : character; 4205end record; 4206for r'size use 16; 4207@end example 4208 4209Without a pragma Pack, each Boolean field requires 8 bits, so the 4210minimum size is 72 bits, but with a pragma Pack, 16 bits would be 4211sufficient. The use of pragma Implicit_Packing allows this record 4212declaration to compile without an explicit pragma Pack. 4213 4214@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 4215@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7b} 4216@section Pragma Import_Function 4217 4218 4219Syntax: 4220 4221@example 4222pragma Import_Function ( 4223 [Internal =>] LOCAL_NAME, 4224 [, [External =>] EXTERNAL_SYMBOL] 4225 [, [Parameter_Types =>] PARAMETER_TYPES] 4226 [, [Result_Type =>] SUBTYPE_MARK] 4227 [, [Mechanism =>] MECHANISM] 4228 [, [Result_Mechanism =>] MECHANISM_NAME]); 4229 4230EXTERNAL_SYMBOL ::= 4231 IDENTIFIER 4232| static_string_EXPRESSION 4233 4234PARAMETER_TYPES ::= 4235 null 4236| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4237 4238TYPE_DESIGNATOR ::= 4239 subtype_NAME 4240| subtype_Name ' Access 4241 4242MECHANISM ::= 4243 MECHANISM_NAME 4244| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4245 4246MECHANISM_ASSOCIATION ::= 4247 [formal_parameter_NAME =>] MECHANISM_NAME 4248 4249MECHANISM_NAME ::= 4250 Value 4251| Reference 4252@end example 4253 4254This pragma is used in conjunction with a pragma @code{Import} to 4255specify additional information for an imported function. The pragma 4256@code{Import} (or equivalent pragma @code{Interface}) must precede the 4257@code{Import_Function} pragma and both must appear in the same 4258declarative part as the function specification. 4259 4260The @code{Internal} argument must uniquely designate 4261the function to which the 4262pragma applies. If more than one function name exists of this name in 4263the declarative part you must use the @code{Parameter_Types} and 4264@code{Result_Type} parameters to achieve the required unique 4265designation. Subtype marks in these parameters must exactly match the 4266subtypes in the corresponding function specification, using positional 4267notation to match parameters with subtype marks. 4268The form with an @code{'Access} attribute can be used to match an 4269anonymous access parameter. 4270 4271You may optionally use the @code{Mechanism} and @code{Result_Mechanism} 4272parameters to specify passing mechanisms for the 4273parameters and result. If you specify a single mechanism name, it 4274applies to all parameters. Otherwise you may specify a mechanism on a 4275parameter by parameter basis using either positional or named 4276notation. If the mechanism is not specified, the default mechanism 4277is used. 4278 4279@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 4280@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7c} 4281@section Pragma Import_Object 4282 4283 4284Syntax: 4285 4286@example 4287pragma Import_Object 4288 [Internal =>] LOCAL_NAME 4289 [, [External =>] EXTERNAL_SYMBOL] 4290 [, [Size =>] EXTERNAL_SYMBOL]); 4291 4292EXTERNAL_SYMBOL ::= 4293 IDENTIFIER 4294| static_string_EXPRESSION 4295@end example 4296 4297This pragma designates an object as imported, and apart from the 4298extended rules for external symbols, is identical in effect to the use of 4299the normal @code{Import} pragma applied to an object. Unlike the 4300subprogram case, you need not use a separate @code{Import} pragma, 4301although you may do so (and probably should do so from a portability 4302point of view). @code{size} is syntax checked, but otherwise ignored by 4303GNAT. 4304 4305@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 4306@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7d} 4307@section Pragma Import_Procedure 4308 4309 4310Syntax: 4311 4312@example 4313pragma Import_Procedure ( 4314 [Internal =>] LOCAL_NAME 4315 [, [External =>] EXTERNAL_SYMBOL] 4316 [, [Parameter_Types =>] PARAMETER_TYPES] 4317 [, [Mechanism =>] MECHANISM]); 4318 4319EXTERNAL_SYMBOL ::= 4320 IDENTIFIER 4321| static_string_EXPRESSION 4322 4323PARAMETER_TYPES ::= 4324 null 4325| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4326 4327TYPE_DESIGNATOR ::= 4328 subtype_NAME 4329| subtype_Name ' Access 4330 4331MECHANISM ::= 4332 MECHANISM_NAME 4333| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4334 4335MECHANISM_ASSOCIATION ::= 4336 [formal_parameter_NAME =>] MECHANISM_NAME 4337 4338MECHANISM_NAME ::= Value | Reference 4339@end example 4340 4341This pragma is identical to @code{Import_Function} except that it 4342applies to a procedure rather than a function and the parameters 4343@code{Result_Type} and @code{Result_Mechanism} are not permitted. 4344 4345@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4346@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7e} 4347@section Pragma Import_Valued_Procedure 4348 4349 4350Syntax: 4351 4352@example 4353pragma Import_Valued_Procedure ( 4354 [Internal =>] LOCAL_NAME 4355 [, [External =>] EXTERNAL_SYMBOL] 4356 [, [Parameter_Types =>] PARAMETER_TYPES] 4357 [, [Mechanism =>] MECHANISM]); 4358 4359EXTERNAL_SYMBOL ::= 4360 IDENTIFIER 4361| static_string_EXPRESSION 4362 4363PARAMETER_TYPES ::= 4364 null 4365| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4366 4367TYPE_DESIGNATOR ::= 4368 subtype_NAME 4369| subtype_Name ' Access 4370 4371MECHANISM ::= 4372 MECHANISM_NAME 4373| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4374 4375MECHANISM_ASSOCIATION ::= 4376 [formal_parameter_NAME =>] MECHANISM_NAME 4377 4378MECHANISM_NAME ::= Value | Reference 4379@end example 4380 4381This pragma is identical to @code{Import_Procedure} except that the 4382first parameter of @code{LOCAL_NAME}, which must be present, must be of 4383mode @code{out}, and externally the subprogram is treated as a function 4384with this parameter as the result of the function. The purpose of this 4385capability is to allow the use of @code{out} and @code{in out} 4386parameters in interfacing to external functions (which are not permitted 4387in Ada functions). You may optionally use the @code{Mechanism} 4388parameters to specify passing mechanisms for the parameters. 4389If you specify a single mechanism name, it applies to all parameters. 4390Otherwise you may specify a mechanism on a parameter by parameter 4391basis using either positional or named notation. If the mechanism is not 4392specified, the default mechanism is used. 4393 4394Note that it is important to use this pragma in conjunction with a separate 4395pragma Import that specifies the desired convention, since otherwise the 4396default convention is Ada, which is almost certainly not what is required. 4397 4398@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4399@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7f} 4400@section Pragma Independent 4401 4402 4403Syntax: 4404 4405@example 4406pragma Independent (Local_NAME); 4407@end example 4408 4409This pragma is standard in Ada 2012 mode (which also provides an aspect 4410of the same name). It is also available as an implementation-defined 4411pragma in all earlier versions. It specifies that the 4412designated object or all objects of the designated type must be 4413independently addressable. This means that separate tasks can safely 4414manipulate such objects. For example, if two components of a record are 4415independent, then two separate tasks may access these two components. 4416This may place 4417constraints on the representation of the object (for instance prohibiting 4418tight packing). 4419 4420@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4421@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{80} 4422@section Pragma Independent_Components 4423 4424 4425Syntax: 4426 4427@example 4428pragma Independent_Components (Local_NAME); 4429@end example 4430 4431This pragma is standard in Ada 2012 mode (which also provides an aspect 4432of the same name). It is also available as an implementation-defined 4433pragma in all earlier versions. It specifies that the components of the 4434designated object, or the components of each object of the designated 4435type, must be 4436independently addressable. This means that separate tasks can safely 4437manipulate separate components in the composite object. This may place 4438constraints on the representation of the object (for instance prohibiting 4439tight packing). 4440 4441@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4442@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{82} 4443@section Pragma Initial_Condition 4444 4445 4446Syntax: 4447 4448@example 4449pragma Initial_Condition (boolean_EXPRESSION); 4450@end example 4451 4452For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} 4453in the SPARK 2014 Reference Manual, section 7.1.6. 4454 4455@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4456@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{83} 4457@section Pragma Initialize_Scalars 4458 4459 4460@geindex debugging with Initialize_Scalars 4461 4462Syntax: 4463 4464@example 4465pragma Initialize_Scalars 4466 [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; 4467 4468TYPE_VALUE_PAIR ::= 4469 SCALAR_TYPE => static_EXPRESSION 4470 4471SCALAR_TYPE := 4472 Short_Float 4473| Float 4474| Long_Float 4475| Long_Long_Flat 4476| Signed_8 4477| Signed_16 4478| Signed_32 4479| Signed_64 4480| Unsigned_8 4481| Unsigned_16 4482| Unsigned_32 4483| Unsigned_64 4484@end example 4485 4486This pragma is similar to @code{Normalize_Scalars} conceptually but has two 4487important differences. 4488 4489First, there is no requirement for the pragma to be used uniformly in all units 4490of a partition. In particular, it is fine to use this just for some or all of 4491the application units of a partition, without needing to recompile the run-time 4492library. In the case where some units are compiled with the pragma, and some 4493without, then a declaration of a variable where the type is defined in package 4494Standard or is locally declared will always be subject to initialization, as 4495will any declaration of a scalar variable. For composite variables, whether the 4496variable is initialized may also depend on whether the package in which the 4497type of the variable is declared is compiled with the pragma. 4498 4499The other important difference is that the programmer can control the value 4500used for initializing scalar objects. This effect can be achieved in several 4501different ways: 4502 4503 4504@itemize * 4505 4506@item 4507At compile time, the programmer can specify the invalid value for a 4508particular family of scalar types using the optional arguments of the pragma. 4509 4510The compile-time approach is intended to optimize the generated code for the 4511pragma, by possibly using fast operations such as @code{memset}. Note that such 4512optimizations require using values where the bytes all have the same binary 4513representation. 4514 4515@item 4516At bind time, the programmer has several options: 4517 4518 4519@itemize * 4520 4521@item 4522Initialization with invalid values (similar to Normalize_Scalars, though 4523for Initialize_Scalars it is not always possible to determine the invalid 4524values in complex cases like signed component fields with nonstandard 4525sizes). 4526 4527@item 4528Initialization with high values. 4529 4530@item 4531Initialization with low values. 4532 4533@item 4534Initialization with a specific bit pattern. 4535@end itemize 4536 4537See the GNAT User's Guide for binder options for specifying these cases. 4538 4539The bind-time approach is intended to provide fast turnaround for testing 4540with different values, without having to recompile the program. 4541 4542@item 4543At execution time, the programmer can specify the invalid values using an 4544environment variable. See the GNAT User's Guide for details. 4545 4546The execution-time approach is intended to provide fast turnaround for 4547testing with different values, without having to recompile and rebind the 4548program. 4549@end itemize 4550 4551Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction 4552with the enhanced validity checking that is now provided in GNAT, which checks 4553for invalid values under more conditions. Using this feature (see description 4554of the @emph{-gnatV} flag in the GNAT User's Guide) in conjunction with pragma 4555@code{Initialize_Scalars} provides a powerful new tool to assist in the detection 4556of problems caused by uninitialized variables. 4557 4558Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the 4559generated code. This may cause your code to be substantially larger. It may 4560also cause an increase in the amount of stack required, so it is probably a 4561good idea to turn on stack checking (see description of stack checking in the 4562GNAT User's Guide) when using this pragma. 4563 4564@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4565@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{84}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{85} 4566@section Pragma Initializes 4567 4568 4569Syntax: 4570 4571@example 4572pragma Initializes (INITIALIZATION_LIST); 4573 4574INITIALIZATION_LIST ::= 4575 null 4576 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4577 4578INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4579 4580INPUT_LIST ::= 4581 null 4582 | INPUT 4583 | (INPUT @{, INPUT@}) 4584 4585INPUT ::= name 4586@end example 4587 4588For the semantics of this pragma, see the entry for aspect @code{Initializes} in the 4589SPARK 2014 Reference Manual, section 7.1.5. 4590 4591@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4592@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{86}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{87} 4593@section Pragma Inline_Always 4594 4595 4596Syntax: 4597 4598@example 4599pragma Inline_Always (NAME [, NAME]); 4600@end example 4601 4602Similar to pragma @code{Inline} except that inlining is unconditional. 4603Inline_Always instructs the compiler to inline every direct call to the 4604subprogram or else to emit a compilation error, independently of any 4605option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. 4606It is an error to take the address or access of @code{NAME}. It is also an error to 4607apply this pragma to a primitive operation of a tagged type. Thanks to such 4608restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. 4609 4610@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4611@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{88} 4612@section Pragma Inline_Generic 4613 4614 4615Syntax: 4616 4617@example 4618pragma Inline_Generic (GNAME @{, GNAME@}); 4619 4620GNAME ::= generic_unit_NAME | generic_instance_NAME 4621@end example 4622 4623This pragma is provided for compatibility with Dec Ada 83. It has 4624no effect in GNAT (which always inlines generics), other 4625than to check that the given names are all names of generic units or 4626generic instances. 4627 4628@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4629@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{89} 4630@section Pragma Interface 4631 4632 4633Syntax: 4634 4635@example 4636pragma Interface ( 4637 [Convention =>] convention_identifier, 4638 [Entity =>] local_NAME 4639 [, [External_Name =>] static_string_expression] 4640 [, [Link_Name =>] static_string_expression]); 4641@end example 4642 4643This pragma is identical in syntax and semantics to 4644the standard Ada pragma @code{Import}. It is provided for compatibility 4645with Ada 83. The definition is upwards compatible both with pragma 4646@code{Interface} as defined in the Ada 83 Reference Manual, and also 4647with some extended implementations of this pragma in certain Ada 83 4648implementations. The only difference between pragma @code{Interface} 4649and pragma @code{Import} is that there is special circuitry to allow 4650both pragmas to appear for the same subprogram entity (normally it 4651is illegal to have multiple @code{Import} pragmas. This is useful in 4652maintaining Ada 83/Ada 95 compatibility and is compatible with other 4653Ada 83 compilers. 4654 4655@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4656@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{8a} 4657@section Pragma Interface_Name 4658 4659 4660Syntax: 4661 4662@example 4663pragma Interface_Name ( 4664 [Entity =>] LOCAL_NAME 4665 [, [External_Name =>] static_string_EXPRESSION] 4666 [, [Link_Name =>] static_string_EXPRESSION]); 4667@end example 4668 4669This pragma provides an alternative way of specifying the interface name 4670for an interfaced subprogram, and is provided for compatibility with Ada 467183 compilers that use the pragma for this purpose. You must provide at 4672least one of @code{External_Name} or @code{Link_Name}. 4673 4674@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4675@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8b} 4676@section Pragma Interrupt_Handler 4677 4678 4679Syntax: 4680 4681@example 4682pragma Interrupt_Handler (procedure_LOCAL_NAME); 4683@end example 4684 4685This program unit pragma is supported for parameterless protected procedures 4686as described in Annex C of the Ada Reference Manual. On the AAMP target 4687the pragma can also be specified for nonprotected parameterless procedures 4688that are declared at the library level (which includes procedures 4689declared at the top level of a library package). In the case of AAMP, 4690when this pragma is applied to a nonprotected procedure, the instruction 4691@code{IERET} is generated for returns from the procedure, enabling 4692maskable interrupts, in place of the normal return instruction. 4693 4694@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4695@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8c} 4696@section Pragma Interrupt_State 4697 4698 4699Syntax: 4700 4701@example 4702pragma Interrupt_State 4703 ([Name =>] value, 4704 [State =>] SYSTEM | RUNTIME | USER); 4705@end example 4706 4707Normally certain interrupts are reserved to the implementation. Any attempt 4708to attach an interrupt causes Program_Error to be raised, as described in 4709RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 4710many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4711reserved to the implementation, so that @code{Ctrl-C} can be used to 4712interrupt execution. Additionally, signals such as @code{SIGSEGV}, 4713@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 4714Ada exceptions, or used to implement run-time functions such as the 4715@code{abort} statement and stack overflow checking. 4716 4717Pragma @code{Interrupt_State} provides a general mechanism for overriding 4718such uses of interrupts. It subsumes the functionality of pragma 4719@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 4720available on Windows. On all other platforms than VxWorks, 4721it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4722and may be used to mark interrupts required by the board support package 4723as reserved. 4724 4725Interrupts can be in one of three states: 4726 4727 4728@itemize * 4729 4730@item 4731System 4732 4733The interrupt is reserved (no Ada handler can be installed), and the 4734Ada run-time may not install a handler. As a result you are guaranteed 4735standard system default action if this interrupt is raised. This also allows 4736installing a low level handler via C APIs such as sigaction(), outside 4737of Ada control. 4738 4739@item 4740Runtime 4741 4742The interrupt is reserved (no Ada handler can be installed). The run time 4743is allowed to install a handler for internal control purposes, but is 4744not required to do so. 4745 4746@item 4747User 4748 4749The interrupt is unreserved. The user may install an Ada handler via 4750Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 4751some other action. 4752@end itemize 4753 4754These states are the allowed values of the @code{State} parameter of the 4755pragma. The @code{Name} parameter is a value of the type 4756@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4757@code{Ada.Interrupts.Names}. 4758 4759This is a configuration pragma, and the binder will check that there 4760are no inconsistencies between different units in a partition in how a 4761given interrupt is specified. It may appear anywhere a pragma is legal. 4762 4763The effect is to move the interrupt to the specified state. 4764 4765By declaring interrupts to be SYSTEM, you guarantee the standard system 4766action, such as a core dump. 4767 4768By declaring interrupts to be USER, you guarantee that you can install 4769a handler. 4770 4771Note that certain signals on many operating systems cannot be caught and 4772handled by applications. In such cases, the pragma is ignored. See the 4773operating system documentation, or the value of the array @code{Reserved} 4774declared in the spec of package @code{System.OS_Interface}. 4775 4776Overriding the default state of signals used by the Ada runtime may interfere 4777with an application's runtime behavior in the cases of the synchronous signals, 4778and in the case of the signal used to implement the @code{abort} statement. 4779 4780@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4781@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8d}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8e} 4782@section Pragma Invariant 4783 4784 4785Syntax: 4786 4787@example 4788pragma Invariant 4789 ([Entity =>] private_type_LOCAL_NAME, 4790 [Check =>] EXPRESSION 4791 [,[Message =>] String_Expression]); 4792@end example 4793 4794This pragma provides exactly the same capabilities as the Type_Invariant aspect 4795defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4796Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4797requires the use of the aspect syntax, which is not available except in 2012 4798mode, it is not possible to use the Type_Invariant aspect in earlier versions 4799of Ada. However the Invariant pragma may be used in any version of Ada. Also 4800note that the aspect Invariant is a synonym in GNAT for the aspect 4801Type_Invariant, but there is no pragma Type_Invariant. 4802 4803The pragma must appear within the visible part of the package specification, 4804after the type to which its Entity argument appears. As with the Invariant 4805aspect, the Check expression is not analyzed until the end of the visible 4806part of the package, so it may contain forward references. The Message 4807argument, if present, provides the exception message used if the invariant 4808is violated. If no Message parameter is provided, a default message that 4809identifies the line on which the pragma appears is used. 4810 4811It is permissible to have multiple Invariants for the same type entity, in 4812which case they are and'ed together. It is permissible to use this pragma 4813in Ada 2012 mode, but you cannot have both an invariant aspect and an 4814invariant pragma for the same entity. 4815 4816For further details on the use of this pragma, see the Ada 2012 documentation 4817of the Type_Invariant aspect. 4818 4819@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4820@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8f} 4821@section Pragma Keep_Names 4822 4823 4824Syntax: 4825 4826@example 4827pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4828@end example 4829 4830The @code{LOCAL_NAME} argument 4831must refer to an enumeration first subtype 4832in the current declarative part. The effect is to retain the enumeration 4833literal names for use by @code{Image} and @code{Value} even if a global 4834@code{Discard_Names} pragma applies. This is useful when you want to 4835generally suppress enumeration literal names and for example you therefore 4836use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you 4837want to retain the names for specific enumeration types. 4838 4839@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4840@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{90} 4841@section Pragma License 4842 4843 4844@geindex License checking 4845 4846Syntax: 4847 4848@example 4849pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4850@end example 4851 4852This pragma is provided to allow automated checking for appropriate license 4853conditions with respect to the standard and modified GPL. A pragma 4854@code{License}, which is a configuration pragma that typically appears at 4855the start of a source file or in a separate @code{gnat.adc} file, specifies 4856the licensing conditions of a unit as follows: 4857 4858 4859@itemize * 4860 4861@item 4862Unrestricted 4863This is used for a unit that can be freely used with no license restrictions. 4864Examples of such units are public domain units, and units from the Ada 4865Reference Manual. 4866 4867@item 4868GPL 4869This is used for a unit that is licensed under the unmodified GPL, and which 4870therefore cannot be @code{with}ed by a restricted unit. 4871 4872@item 4873Modified_GPL 4874This is used for a unit licensed under the GNAT modified GPL that includes 4875a special exception paragraph that specifically permits the inclusion of 4876the unit in programs without requiring the entire program to be released 4877under the GPL. 4878 4879@item 4880Restricted 4881This is used for a unit that is restricted in that it is not permitted to 4882depend on units that are licensed under the GPL. Typical examples are 4883proprietary code that is to be released under more restrictive license 4884conditions. Note that restricted units are permitted to @code{with} units 4885which are licensed under the modified GPL (this is the whole point of the 4886modified GPL). 4887@end itemize 4888 4889Normally a unit with no @code{License} pragma is considered to have an 4890unknown license, and no checking is done. However, standard GNAT headers 4891are recognized, and license information is derived from them as follows. 4892 4893A GNAT license header starts with a line containing 78 hyphens. The following 4894comment text is searched for the appearance of any of the following strings. 4895 4896If the string 'GNU General Public License' is found, then the unit is assumed 4897to have GPL license, unless the string 'As a special exception' follows, in 4898which case the license is assumed to be modified GPL. 4899 4900If one of the strings 4901'This specification is adapted from the Ada Semantic Interface' or 4902'This specification is derived from the Ada Reference Manual' is found 4903then the unit is assumed to be unrestricted. 4904 4905These default actions means that a program with a restricted license pragma 4906will automatically get warnings if a GPL unit is inappropriately 4907@code{with}ed. For example, the program: 4908 4909@example 4910with Sem_Ch3; 4911with GNAT.Sockets; 4912procedure Secret_Stuff is 4913 ... 4914end Secret_Stuff 4915@end example 4916 4917if compiled with pragma @code{License} (@code{Restricted}) in a 4918@code{gnat.adc} file will generate the warning: 4919 4920@example 49211. with Sem_Ch3; 4922 | 4923 >>> license of withed unit "Sem_Ch3" is incompatible 4924 49252. with GNAT.Sockets; 49263. procedure Secret_Stuff is 4927@end example 4928 4929Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 4930compiler and is licensed under the 4931GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 4932run time, and is therefore licensed under the modified GPL. 4933 4934@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 4935@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{91} 4936@section Pragma Link_With 4937 4938 4939Syntax: 4940 4941@example 4942pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4943@end example 4944 4945This pragma is provided for compatibility with certain Ada 83 compilers. 4946It has exactly the same effect as pragma @code{Linker_Options} except 4947that spaces occurring within one of the string expressions are treated 4948as separators. For example, in the following case: 4949 4950@example 4951pragma Link_With ("-labc -ldef"); 4952@end example 4953 4954results in passing the strings @code{-labc} and @code{-ldef} as two 4955separate arguments to the linker. In addition pragma Link_With allows 4956multiple arguments, with the same effect as successive pragmas. 4957 4958@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 4959@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{92} 4960@section Pragma Linker_Alias 4961 4962 4963Syntax: 4964 4965@example 4966pragma Linker_Alias ( 4967 [Entity =>] LOCAL_NAME, 4968 [Target =>] static_string_EXPRESSION); 4969@end example 4970 4971@code{LOCAL_NAME} must refer to an object that is declared at the library 4972level. This pragma establishes the given entity as a linker alias for the 4973given target. It is equivalent to @code{__attribute__((alias))} in GNU C 4974and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol 4975@code{static_string_EXPRESSION} in the object file, that is to say no space 4976is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved 4977to the same address as @code{static_string_EXPRESSION} by the linker. 4978 4979The actual linker name for the target must be used (e.g., the fully 4980encoded name with qualification in Ada, or the mangled name in C++), 4981or it must be declared using the C convention with @code{pragma Import} 4982or @code{pragma Export}. 4983 4984Not all target machines support this pragma. On some of them it is accepted 4985only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. 4986 4987@example 4988-- Example of the use of pragma Linker_Alias 4989 4990package p is 4991 i : Integer := 1; 4992 pragma Export (C, i); 4993 4994 new_name_for_i : Integer; 4995 pragma Linker_Alias (new_name_for_i, "i"); 4996end p; 4997@end example 4998 4999@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 5000@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{93} 5001@section Pragma Linker_Constructor 5002 5003 5004Syntax: 5005 5006@example 5007pragma Linker_Constructor (procedure_LOCAL_NAME); 5008@end example 5009 5010@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 5011is declared at the library level. A procedure to which this pragma is 5012applied will be treated as an initialization routine by the linker. 5013It is equivalent to @code{__attribute__((constructor))} in GNU C and 5014causes @code{procedure_LOCAL_NAME} to be invoked before the entry point 5015of the executable is called (or immediately after the shared library is 5016loaded if the procedure is linked in a shared library), in particular 5017before the Ada run-time environment is set up. 5018 5019Because of these specific contexts, the set of operations such a procedure 5020can perform is very limited and the type of objects it can manipulate is 5021essentially restricted to the elementary types. In particular, it must only 5022contain code to which pragma Restrictions (No_Elaboration_Code) applies. 5023 5024This pragma is used by GNAT to implement auto-initialization of shared Stand 5025Alone Libraries, which provides a related capability without the restrictions 5026listed above. Where possible, the use of Stand Alone Libraries is preferable 5027to the use of this pragma. 5028 5029@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 5030@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{94} 5031@section Pragma Linker_Destructor 5032 5033 5034Syntax: 5035 5036@example 5037pragma Linker_Destructor (procedure_LOCAL_NAME); 5038@end example 5039 5040@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 5041is declared at the library level. A procedure to which this pragma is 5042applied will be treated as a finalization routine by the linker. 5043It is equivalent to @code{__attribute__((destructor))} in GNU C and 5044causes @code{procedure_LOCAL_NAME} to be invoked after the entry point 5045of the executable has exited (or immediately before the shared library 5046is unloaded if the procedure is linked in a shared library), in particular 5047after the Ada run-time environment is shut down. 5048 5049See @code{pragma Linker_Constructor} for the set of restrictions that apply 5050because of these specific contexts. 5051 5052@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 5053@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{95}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{96} 5054@section Pragma Linker_Section 5055 5056 5057Syntax: 5058 5059@example 5060pragma Linker_Section ( 5061 [Entity =>] LOCAL_NAME, 5062 [Section =>] static_string_EXPRESSION); 5063@end example 5064 5065@code{LOCAL_NAME} must refer to an object, type, or subprogram that is 5066declared at the library level. This pragma specifies the name of the 5067linker section for the given entity. It is equivalent to 5068@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to 5069be placed in the @code{static_string_EXPRESSION} section of the 5070executable (assuming the linker doesn't rename the section). 5071GNAT also provides an implementation defined aspect of the same name. 5072 5073In the case of specifying this aspect for a type, the effect is to 5074specify the corresponding section for all library-level objects of 5075the type that do not have an explicit linker section set. Note that 5076this only applies to whole objects, not to components of composite objects. 5077 5078In the case of a subprogram, the linker section applies to all previously 5079declared matching overloaded subprograms in the current declarative part 5080which do not already have a linker section assigned. The linker section 5081aspect is useful in this case for specifying different linker sections 5082for different elements of such an overloaded set. 5083 5084Note that an empty string specifies that no linker section is specified. 5085This is not quite the same as omitting the pragma or aspect, since it 5086can be used to specify that one element of an overloaded set of subprograms 5087has the default linker section, or that one object of a type for which a 5088linker section is specified should has the default linker section. 5089 5090The compiler normally places library-level entities in standard sections 5091depending on the class: procedures and functions generally go in the 5092@code{.text} section, initialized variables in the @code{.data} section 5093and uninitialized variables in the @code{.bss} section. 5094 5095Other, special sections may exist on given target machines to map special 5096hardware, for example I/O ports or flash memory. This pragma is a means to 5097defer the final layout of the executable to the linker, thus fully working 5098at the symbolic level with the compiler. 5099 5100Some file formats do not support arbitrary sections so not all target 5101machines support this pragma. The use of this pragma may cause a program 5102execution to be erroneous if it is used to place an entity into an 5103inappropriate section (e.g., a modified variable into the @code{.text} 5104section). See also @code{pragma Persistent_BSS}. 5105 5106@example 5107-- Example of the use of pragma Linker_Section 5108 5109package IO_Card is 5110 Port_A : Integer; 5111 pragma Volatile (Port_A); 5112 pragma Linker_Section (Port_A, ".bss.port_a"); 5113 5114 Port_B : Integer; 5115 pragma Volatile (Port_B); 5116 pragma Linker_Section (Port_B, ".bss.port_b"); 5117 5118 type Port_Type is new Integer with Linker_Section => ".bss"; 5119 PA : Port_Type with Linker_Section => ".bss.PA"; 5120 PB : Port_Type; -- ends up in linker section ".bss" 5121 5122 procedure Q with Linker_Section => "Qsection"; 5123end IO_Card; 5124@end example 5125 5126@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 5127@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{97}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{98} 5128@section Pragma Lock_Free 5129 5130 5131Syntax: 5132This pragma may be specified for protected types or objects. It specifies that 5133the implementation of protected operations must be implemented without locks. 5134Compilation fails if the compiler cannot generate lock-free code for the 5135operations. 5136 5137The current conditions required to support this pragma are: 5138 5139 5140@itemize * 5141 5142@item 5143Protected type declarations may not contain entries 5144 5145@item 5146Protected subprogram declarations may not have nonelementary parameters 5147@end itemize 5148 5149In addition, each protected subprogram body must satisfy: 5150 5151 5152@itemize * 5153 5154@item 5155May reference only one protected component 5156 5157@item 5158May not reference nonconstant entities outside the protected subprogram 5159scope. 5160 5161@item 5162May not contain address representation items, allocators, or quantified 5163expressions. 5164 5165@item 5166May not contain delay, goto, loop, or procedure-call statements. 5167 5168@item 5169May not contain exported and imported entities 5170 5171@item 5172May not dereferenced access values 5173 5174@item 5175Function calls and attribute references must be static 5176@end itemize 5177 5178@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 5179@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{99} 5180@section Pragma Loop_Invariant 5181 5182 5183Syntax: 5184 5185@example 5186pragma Loop_Invariant ( boolean_EXPRESSION ); 5187@end example 5188 5189The effect of this pragma is similar to that of pragma @code{Assert}, 5190except that in an @code{Assertion_Policy} pragma, the identifier 5191@code{Loop_Invariant} is used to control whether it is ignored or checked 5192(or disabled). 5193 5194@code{Loop_Invariant} can only appear as one of the items in the sequence 5195of statements of a loop body, or nested inside block statements that 5196appear in the sequence of statements of a loop body. 5197The intention is that it be used to 5198represent a "loop invariant" assertion, i.e. something that is true each 5199time through the loop, and which can be used to show that the loop is 5200achieving its purpose. 5201 5202Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5203apply to the same loop should be grouped in the same sequence of 5204statements. 5205 5206To aid in writing such invariants, the special attribute @code{Loop_Entry} 5207may be used to refer to the value of an expression on entry to the loop. This 5208attribute can only be used within the expression of a @code{Loop_Invariant} 5209pragma. For full details, see documentation of attribute @code{Loop_Entry}. 5210 5211@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 5212@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{9a} 5213@section Pragma Loop_Optimize 5214 5215 5216Syntax: 5217 5218@example 5219pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 5220 5221OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 5222@end example 5223 5224This pragma must appear immediately within a loop statement. It allows the 5225programmer to specify optimization hints for the enclosing loop. The hints 5226are not mutually exclusive and can be freely mixed, but not all combinations 5227will yield a sensible outcome. 5228 5229There are five supported optimization hints for a loop: 5230 5231 5232@itemize * 5233 5234@item 5235Ivdep 5236 5237The programmer asserts that there are no loop-carried dependencies 5238which would prevent consecutive iterations of the loop from being 5239executed simultaneously. 5240 5241@item 5242No_Unroll 5243 5244The loop must not be unrolled. This is a strong hint: the compiler will not 5245unroll a loop marked with this hint. 5246 5247@item 5248Unroll 5249 5250The loop should be unrolled. This is a weak hint: the compiler will try to 5251apply unrolling to this loop preferably to other optimizations, notably 5252vectorization, but there is no guarantee that the loop will be unrolled. 5253 5254@item 5255No_Vector 5256 5257The loop must not be vectorized. This is a strong hint: the compiler will not 5258vectorize a loop marked with this hint. 5259 5260@item 5261Vector 5262 5263The loop should be vectorized. This is a weak hint: the compiler will try to 5264apply vectorization to this loop preferably to other optimizations, notably 5265unrolling, but there is no guarantee that the loop will be vectorized. 5266@end itemize 5267 5268These hints do not remove the need to pass the appropriate switches to the 5269compiler in order to enable the relevant optimizations, that is to say 5270@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 5271vectorization. 5272 5273@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 5274@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9b} 5275@section Pragma Loop_Variant 5276 5277 5278Syntax: 5279 5280@example 5281pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 5282LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 5283CHANGE_DIRECTION ::= Increases | Decreases 5284@end example 5285 5286@code{Loop_Variant} can only appear as one of the items in the sequence 5287of statements of a loop body, or nested inside block statements that 5288appear in the sequence of statements of a loop body. 5289It allows the specification of quantities which must always 5290decrease or increase in successive iterations of the loop. In its simplest 5291form, just one expression is specified, whose value must increase or decrease 5292on each iteration of the loop. 5293 5294In a more complex form, multiple arguments can be given which are intepreted 5295in a nesting lexicographic manner. For example: 5296 5297@example 5298pragma Loop_Variant (Increases => X, Decreases => Y); 5299@end example 5300 5301specifies that each time through the loop either X increases, or X stays 5302the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 5303loop is making progress. It can be useful in helping to show informally 5304or prove formally that the loop always terminates. 5305 5306@code{Loop_Variant} is an assertion whose effect can be controlled using 5307an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 5308policy can be @code{Check} to enable the loop variant check, @code{Ignore} 5309to ignore the check (in which case the pragma has no effect on the program), 5310or @code{Disable} in which case the pragma is not even checked for correct 5311syntax. 5312 5313Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5314apply to the same loop should be grouped in the same sequence of 5315statements. 5316 5317The @code{Loop_Entry} attribute may be used within the expressions of the 5318@code{Loop_Variant} pragma to refer to values on entry to the loop. 5319 5320@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 5321@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9c} 5322@section Pragma Machine_Attribute 5323 5324 5325Syntax: 5326 5327@example 5328pragma Machine_Attribute ( 5329 [Entity =>] LOCAL_NAME, 5330 [Attribute_Name =>] static_string_EXPRESSION 5331 [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); 5332@end example 5333 5334Machine-dependent attributes can be specified for types and/or 5335declarations. This pragma is semantically equivalent to 5336@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not 5337specified) or @code{__attribute__((@emph{attribute_name(info})))} 5338or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C, 5339where @emph{attribute_name} is recognized by the compiler middle-end 5340or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note 5341that a string literal for the optional parameter @code{info} or the 5342following ones is transformed by default into an identifier, 5343which may make this pragma unusable for some attributes. 5344For further information see @cite{GNU Compiler Collection (GCC) Internals}. 5345 5346@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 5347@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9d} 5348@section Pragma Main 5349 5350 5351Syntax: 5352 5353@example 5354pragma Main 5355 (MAIN_OPTION [, MAIN_OPTION]); 5356 5357MAIN_OPTION ::= 5358 [Stack_Size =>] static_integer_EXPRESSION 5359| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 5360| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 5361@end example 5362 5363This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5364no effect in GNAT, other than being syntax checked. 5365 5366@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas 5367@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9e} 5368@section Pragma Main_Storage 5369 5370 5371Syntax: 5372 5373@example 5374pragma Main_Storage 5375 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 5376 5377MAIN_STORAGE_OPTION ::= 5378 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 5379| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 5380@end example 5381 5382This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5383no effect in GNAT, other than being syntax checked. 5384 5385@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas 5386@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{a0} 5387@section Pragma Max_Queue_Length 5388 5389 5390Syntax: 5391 5392@example 5393pragma Max_Entry_Queue (static_integer_EXPRESSION); 5394@end example 5395 5396This pragma is used to specify the maximum callers per entry queue for 5397individual protected entries and entry families. It accepts a single 5398integer (-1 or more) as a parameter and must appear after the declaration of an 5399entry. 5400 5401A value of -1 represents no additional restriction on queue length. 5402 5403@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas 5404@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a1} 5405@section Pragma No_Body 5406 5407 5408Syntax: 5409 5410@example 5411pragma No_Body; 5412@end example 5413 5414There are a number of cases in which a package spec does not require a body, 5415and in fact a body is not permitted. GNAT will not permit the spec to be 5416compiled if there is a body around. The pragma No_Body allows you to provide 5417a body file, even in a case where no body is allowed. The body file must 5418contain only comments and a single No_Body pragma. This is recognized by 5419the compiler as indicating that no body is logically present. 5420 5421This is particularly useful during maintenance when a package is modified in 5422such a way that a body needed before is no longer needed. The provision of a 5423dummy body with a No_Body pragma ensures that there is no interference from 5424earlier versions of the package body. 5425 5426@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas 5427@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{a3} 5428@section Pragma No_Caching 5429 5430 5431Syntax: 5432 5433@example 5434pragma No_Caching [ (boolean_EXPRESSION) ]; 5435@end example 5436 5437For the semantics of this pragma, see the entry for aspect @code{No_Caching} in 5438the SPARK 2014 Reference Manual, section 7.1.2. 5439 5440@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas 5441@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a4} 5442@section Pragma No_Component_Reordering 5443 5444 5445Syntax: 5446 5447@example 5448pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 5449@end example 5450 5451@code{type_LOCAL_NAME} must refer to a record type declaration in the current 5452declarative part. The effect is to preclude any reordering of components 5453for the layout of the record, i.e. the record is laid out by the compiler 5454in the order in which the components are declared textually. The form with 5455no argument is a configuration pragma which applies to all record types 5456declared in units to which the pragma applies and there is a requirement 5457that this pragma be used consistently within a partition. 5458 5459@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas 5460@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a6} 5461@section Pragma No_Elaboration_Code_All 5462 5463 5464Syntax: 5465 5466@example 5467pragma No_Elaboration_Code_All [(program_unit_NAME)]; 5468@end example 5469 5470This is a program unit pragma (there is also an equivalent aspect of the 5471same name) that establishes the restriction @code{No_Elaboration_Code} for 5472the current unit and any extended main source units (body and subunits). 5473It also has the effect of enforcing a transitive application of this 5474aspect, so that if any unit is implicitly or explicitly with'ed by the 5475current unit, it must also have the No_Elaboration_Code_All aspect set. 5476It may be applied to package or subprogram specs or their generic versions. 5477 5478@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 5479@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a7} 5480@section Pragma No_Heap_Finalization 5481 5482 5483Syntax: 5484 5485@example 5486pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 5487@end example 5488 5489Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a 5490type-specific pragma. 5491 5492In its configuration form, the pragma must appear within a configuration file 5493such as gnat.adc, without an argument. The pragma suppresses the call to 5494@code{Finalize} for heap-allocated objects created through library-level named 5495access-to-object types in cases where the designated type requires finalization 5496actions. 5497 5498In its type-specific form, the argument of the pragma must denote a 5499library-level named access-to-object type. The pragma suppresses the call to 5500@code{Finalize} for heap-allocated objects created through the specific access type 5501in cases where the designated type requires finalization actions. 5502 5503It is still possible to finalize such heap-allocated objects by explicitly 5504deallocating them. 5505 5506A library-level named access-to-object type declared within a generic unit will 5507lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not 5508appear at the library level. 5509 5510@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas 5511@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a9} 5512@section Pragma No_Inline 5513 5514 5515Syntax: 5516 5517@example 5518pragma No_Inline (NAME @{, NAME@}); 5519@end example 5520 5521This pragma suppresses inlining for the callable entity or the instances of 5522the generic subprogram designated by @code{NAME}, including inlining that 5523results from the use of pragma @code{Inline}. This pragma is always active, 5524in particular it is not subject to the use of option @emph{-gnatn} or 5525@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 5526pragma @code{Inline_Always} for the same @code{NAME}. 5527 5528@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas 5529@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{aa} 5530@section Pragma No_Return 5531 5532 5533Syntax: 5534 5535@example 5536pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5537@end example 5538 5539Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure 5540declarations in the current declarative part. A procedure to which this 5541pragma is applied may not contain any explicit @code{return} statements. 5542In addition, if the procedure contains any implicit returns from falling 5543off the end of a statement sequence, then execution of that implicit 5544return will cause Program_Error to be raised. 5545 5546One use of this pragma is to identify procedures whose only purpose is to raise 5547an exception. Another use of this pragma is to suppress incorrect warnings 5548about missing returns in functions, where the last statement of a function 5549statement sequence is a call to such a procedure. 5550 5551Note that in Ada 2005 mode, this pragma is part of the language. It is 5552available in all earlier versions of Ada as an implementation-defined 5553pragma. 5554 5555@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas 5556@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{ab} 5557@section Pragma No_Strict_Aliasing 5558 5559 5560Syntax: 5561 5562@example 5563pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5564@end example 5565 5566@code{type_LOCAL_NAME} must refer to an access type 5567declaration in the current declarative part. The effect is to inhibit 5568strict aliasing optimization for the given type. The form with no 5569arguments is a configuration pragma which applies to all access types 5570declared in units to which the pragma applies. For a detailed 5571description of the strict aliasing optimization, and the situations 5572in which it must be suppressed, see the section on Optimization and Strict Aliasing 5573in the @cite{GNAT User's Guide}. 5574 5575This pragma currently has no effects on access to unconstrained array types. 5576 5577@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5578@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{ac}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{ad} 5579@section Pragma No_Tagged_Streams 5580 5581 5582Syntax: 5583 5584@example 5585pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5586@end example 5587 5588Normally when a tagged type is introduced using a full type declaration, 5589part of the processing includes generating stream access routines to be 5590used by stream attributes referencing the type (or one of its subtypes 5591or derived types). This can involve the generation of significant amounts 5592of code which is wasted space if stream routines are not needed for the 5593type in question. 5594 5595The @code{No_Tagged_Streams} pragma causes the generation of these stream 5596routines to be skipped, and any attempt to use stream operations on 5597types subject to this pragma will be statically rejected as illegal. 5598 5599There are two forms of the pragma. The form with no arguments must appear 5600in a declarative sequence or in the declarations of a package spec. This 5601pragma affects all subsequent root tagged types declared in the declaration 5602sequence, and specifies that no stream routines be generated. The form with 5603an argument (for which there is also a corresponding aspect) specifies a 5604single root tagged type for which stream routines are not to be generated. 5605 5606Once the pragma has been given for a particular root tagged type, all subtypes 5607and derived types of this type inherit the pragma automatically, so the effect 5608applies to a complete hierarchy (this is necessary to deal with the class-wide 5609dispatching versions of the stream routines). 5610 5611When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously 5612applied to a tagged type its Expanded_Name and External_Tag are initialized 5613with empty strings. This is useful to avoid exposing entity names at binary 5614level but has a negative impact on the debuggability of tagged types. 5615 5616@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5617@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ae} 5618@section Pragma Normalize_Scalars 5619 5620 5621Syntax: 5622 5623@example 5624pragma Normalize_Scalars; 5625@end example 5626 5627This is a language defined pragma which is fully implemented in GNAT. The 5628effect is to cause all scalar objects that are not otherwise initialized 5629to be initialized. The initial values are implementation dependent and 5630are as follows: 5631 5632 5633@table @asis 5634 5635@item @emph{Standard.Character} 5636 5637Objects whose root type is Standard.Character are initialized to 5638Character'Last unless the subtype range excludes NUL (in which case 5639NUL is used). This choice will always generate an invalid value if 5640one exists. 5641 5642@item @emph{Standard.Wide_Character} 5643 5644Objects whose root type is Standard.Wide_Character are initialized to 5645Wide_Character'Last unless the subtype range excludes NUL (in which case 5646NUL is used). This choice will always generate an invalid value if 5647one exists. 5648 5649@item @emph{Standard.Wide_Wide_Character} 5650 5651Objects whose root type is Standard.Wide_Wide_Character are initialized to 5652the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5653which case NUL is used). This choice will always generate an invalid value if 5654one exists. 5655 5656@item @emph{Integer types} 5657 5658Objects of an integer type are treated differently depending on whether 5659negative values are present in the subtype. If no negative values are 5660present, then all one bits is used as the initial value except in the 5661special case where zero is excluded from the subtype, in which case 5662all zero bits are used. This choice will always generate an invalid 5663value if one exists. 5664 5665For subtypes with negative values present, the largest negative number 5666is used, except in the unusual case where this largest negative number 5667is in the subtype, and the largest positive number is not, in which case 5668the largest positive value is used. This choice will always generate 5669an invalid value if one exists. 5670 5671@item @emph{Floating-Point Types} 5672 5673Objects of all floating-point types are initialized to all 1-bits. For 5674standard IEEE format, this corresponds to a NaN (not a number) which is 5675indeed an invalid value. 5676 5677@item @emph{Fixed-Point Types} 5678 5679Objects of all fixed-point types are treated as described above for integers, 5680with the rules applying to the underlying integer value used to represent 5681the fixed-point value. 5682 5683@item @emph{Modular types} 5684 5685Objects of a modular type are initialized to all one bits, except in 5686the special case where zero is excluded from the subtype, in which 5687case all zero bits are used. This choice will always generate an 5688invalid value if one exists. 5689 5690@item @emph{Enumeration types} 5691 5692Objects of an enumeration type are initialized to all one-bits, i.e., to 5693the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 5694whose Pos value is zero, in which case a code of zero is used. This choice 5695will always generate an invalid value if one exists. 5696@end table 5697 5698@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5699@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{af}@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{b0} 5700@section Pragma Obsolescent 5701 5702 5703Syntax: 5704 5705@example 5706pragma Obsolescent; 5707 5708pragma Obsolescent ( 5709 [Message =>] static_string_EXPRESSION 5710[,[Version =>] Ada_05]]); 5711 5712pragma Obsolescent ( 5713 [Entity =>] NAME 5714[,[Message =>] static_string_EXPRESSION 5715[,[Version =>] Ada_05]] ); 5716@end example 5717 5718This pragma can occur immediately following a declaration of an entity, 5719including the case of a record component. If no Entity argument is present, 5720then this declaration is the one to which the pragma applies. If an Entity 5721parameter is present, it must either match the name of the entity in this 5722declaration, or alternatively, the pragma can immediately follow an enumeration 5723type declaration, where the Entity argument names one of the enumeration 5724literals. 5725 5726This pragma is used to indicate that the named entity 5727is considered obsolescent and should not be used. Typically this is 5728used when an API must be modified by eventually removing or modifying 5729existing subprograms or other entities. The pragma can be used at an 5730intermediate stage when the entity is still present, but will be 5731removed later. 5732 5733The effect of this pragma is to output a warning message on a reference to 5734an entity thus marked that the subprogram is obsolescent if the appropriate 5735warning option in the compiler is activated. If the @code{Message} parameter is 5736present, then a second warning message is given containing this text. In 5737addition, a reference to the entity is considered to be a violation of pragma 5738@code{Restrictions (No_Obsolescent_Features)}. 5739 5740This pragma can also be used as a program unit pragma for a package, 5741in which case the entity name is the name of the package, and the 5742pragma indicates that the entire package is considered 5743obsolescent. In this case a client @code{with}ing such a package 5744violates the restriction, and the @code{with} clause is 5745flagged with warnings if the warning option is set. 5746 5747If the @code{Version} parameter is present (which must be exactly 5748the identifier @code{Ada_05}, no other argument is allowed), then the 5749indication of obsolescence applies only when compiling in Ada 2005 5750mode. This is primarily intended for dealing with the situations 5751in the predefined library where subprograms or packages 5752have become defined as obsolescent in Ada 2005 5753(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. 5754 5755The following examples show typical uses of this pragma: 5756 5757@example 5758package p is 5759 pragma Obsolescent (p, Message => "use pp instead of p"); 5760end p; 5761 5762package q is 5763 procedure q2; 5764 pragma Obsolescent ("use q2new instead"); 5765 5766 type R is new integer; 5767 pragma Obsolescent 5768 (Entity => R, 5769 Message => "use RR in Ada 2005", 5770 Version => Ada_05); 5771 5772 type M is record 5773 F1 : Integer; 5774 F2 : Integer; 5775 pragma Obsolescent; 5776 F3 : Integer; 5777 end record; 5778 5779 type E is (a, bc, 'd', quack); 5780 pragma Obsolescent (Entity => bc) 5781 pragma Obsolescent (Entity => 'd') 5782 5783 function "+" 5784 (a, b : character) return character; 5785 pragma Obsolescent (Entity => "+"); 5786end; 5787@end example 5788 5789Note that, as for all pragmas, if you use a pragma argument identifier, 5790then all subsequent parameters must also use a pragma argument identifier. 5791So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} 5792argument is present, it must be preceded by @code{Message =>}. 5793 5794@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5795@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{b1} 5796@section Pragma Optimize_Alignment 5797 5798 5799@geindex Alignment 5800@geindex default settings 5801 5802Syntax: 5803 5804@example 5805pragma Optimize_Alignment (TIME | SPACE | OFF); 5806@end example 5807 5808This is a configuration pragma which affects the choice of default alignments 5809for types and objects where no alignment is explicitly specified. There is a 5810time/space trade-off in the selection of these values. Large alignments result 5811in more efficient code, at the expense of larger data space, since sizes have 5812to be increased to match these alignments. Smaller alignments save space, but 5813the access code is slower. The normal choice of default alignments for types 5814and individual alignment promotions for objects (which is what you get if you 5815do not use this pragma, or if you use an argument of OFF), tries to balance 5816these two requirements. 5817 5818Specifying SPACE causes smaller default alignments to be chosen in two cases. 5819First any packed record is given an alignment of 1. Second, if a size is given 5820for the type, then the alignment is chosen to avoid increasing this size. For 5821example, consider: 5822 5823@example 5824type R is record 5825 X : Integer; 5826 Y : Character; 5827end record; 5828 5829for R'Size use 5*8; 5830@end example 5831 5832In the default mode, this type gets an alignment of 4, so that access to the 5833Integer field X are efficient. But this means that objects of the type end up 5834with a size of 8 bytes. This is a valid choice, since sizes of objects are 5835allowed to be bigger than the size of the type, but it can waste space if for 5836example fields of type R appear in an enclosing record. If the above type is 5837compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5838 5839However, there is one case in which SPACE is ignored. If a variable length 5840record (that is a discriminated record with a component which is an array 5841whose length depends on a discriminant), has a pragma Pack, then it is not 5842in general possible to set the alignment of such a record to one, so the 5843pragma is ignored in this case (with a warning). 5844 5845Specifying SPACE also disables alignment promotions for standalone objects, 5846which occur when the compiler increases the alignment of a specific object 5847without changing the alignment of its type. 5848 5849Specifying SPACE also disables component reordering in unpacked record types, 5850which can result in larger sizes in order to meet alignment requirements. 5851 5852Specifying TIME causes larger default alignments to be chosen in the case of 5853small types with sizes that are not a power of 2. For example, consider: 5854 5855@example 5856type R is record 5857 A : Character; 5858 B : Character; 5859 C : Boolean; 5860end record; 5861 5862pragma Pack (R); 5863for R'Size use 17; 5864@end example 5865 5866The default alignment for this record is normally 1, but if this type is 5867compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 5868to 4, which wastes space for objects of the type, since they are now 4 bytes 5869long, but results in more efficient access when the whole record is referenced. 5870 5871As noted above, this is a configuration pragma, and there is a requirement 5872that all units in a partition be compiled with a consistent setting of the 5873optimization setting. This would normally be achieved by use of a configuration 5874pragma file containing the appropriate setting. The exception to this rule is 5875that units with an explicit configuration pragma in the same file as the source 5876unit are excluded from the consistency check, as are all predefined units. The 5877latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5878pragma appears at the start of the file. 5879 5880@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5881@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b2} 5882@section Pragma Ordered 5883 5884 5885Syntax: 5886 5887@example 5888pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5889@end example 5890 5891Most enumeration types are from a conceptual point of view unordered. 5892For example, consider: 5893 5894@example 5895type Color is (Red, Blue, Green, Yellow); 5896@end example 5897 5898By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 5899but really these relations make no sense; the enumeration type merely 5900specifies a set of possible colors, and the order is unimportant. 5901 5902For unordered enumeration types, it is generally a good idea if 5903clients avoid comparisons (other than equality or inequality) and 5904explicit ranges. (A @emph{client} is a unit where the type is referenced, 5905other than the unit where the type is declared, its body, and its subunits.) 5906For example, if code buried in some client says: 5907 5908@example 5909if Current_Color < Yellow then ... 5910if Current_Color in Blue .. Green then ... 5911@end example 5912 5913then the client code is relying on the order, which is undesirable. 5914It makes the code hard to read and creates maintenance difficulties if 5915entries have to be added to the enumeration type. Instead, 5916the code in the client should list the possibilities, or an 5917appropriate subtype should be declared in the unit that declares 5918the original enumeration type. E.g., the following subtype could 5919be declared along with the type @code{Color}: 5920 5921@example 5922subtype RBG is Color range Red .. Green; 5923@end example 5924 5925and then the client could write: 5926 5927@example 5928if Current_Color in RBG then ... 5929if Current_Color = Blue or Current_Color = Green then ... 5930@end example 5931 5932However, some enumeration types are legitimately ordered from a conceptual 5933point of view. For example, if you declare: 5934 5935@example 5936type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5937@end example 5938 5939then the ordering imposed by the language is reasonable, and 5940clients can depend on it, writing for example: 5941 5942@example 5943if D in Mon .. Fri then ... 5944if D < Wed then ... 5945@end example 5946 5947The pragma @emph{Ordered} is provided to mark enumeration types that 5948are conceptually ordered, alerting the reader that clients may depend 5949on the ordering. GNAT provides a pragma to mark enumerations as ordered 5950rather than one to mark them as unordered, since in our experience, 5951the great majority of enumeration types are conceptually unordered. 5952 5953The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 5954and @code{Wide_Wide_Character} 5955are considered to be ordered types, so each is declared with a 5956pragma @code{Ordered} in package @code{Standard}. 5957 5958Normally pragma @code{Ordered} serves only as documentation and a guide for 5959coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 5960requests warnings for inappropriate uses (comparisons and explicit 5961subranges) for unordered types. If this switch is used, then any 5962enumeration type not marked with pragma @code{Ordered} will be considered 5963as unordered, and will generate warnings for inappropriate uses. 5964 5965Note that generic types are not considered ordered or unordered (since the 5966template can be instantiated for both cases), so we never generate warnings 5967for the case of generic enumerated types. 5968 5969For additional information please refer to the description of the 5970@emph{-gnatw.u} switch in the GNAT User's Guide. 5971 5972@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 5973@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b3} 5974@section Pragma Overflow_Mode 5975 5976 5977Syntax: 5978 5979@example 5980pragma Overflow_Mode 5981 ( [General =>] MODE 5982 [,[Assertions =>] MODE]); 5983 5984MODE ::= STRICT | MINIMIZED | ELIMINATED 5985@end example 5986 5987This pragma sets the current overflow mode to the given setting. For details 5988of the meaning of these modes, please refer to the 5989'Overflow Check Handling in GNAT' appendix in the 5990GNAT User's Guide. If only the @code{General} parameter is present, 5991the given mode applies to all expressions. If both parameters are present, 5992the @code{General} mode applies to expressions outside assertions, and 5993the @code{Eliminated} mode applies to expressions within assertions. 5994 5995The case of the @code{MODE} parameter is ignored, 5996so @code{MINIMIZED}, @code{Minimized} and 5997@code{minimized} all have the same effect. 5998 5999The @code{Overflow_Mode} pragma has the same scoping and placement 6000rules as pragma @code{Suppress}, so it can occur either as a 6001configuration pragma, specifying a default for the whole 6002program, or in a declarative scope, where it applies to the 6003remaining declarations and statements in that scope. 6004 6005The pragma @code{Suppress (Overflow_Check)} suppresses 6006overflow checking, but does not affect the overflow mode. 6007 6008The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 6009overflow checking, but does not affect the overflow mode. 6010 6011@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 6012@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b4} 6013@section Pragma Overriding_Renamings 6014 6015 6016@geindex Rational profile 6017 6018@geindex Rational compatibility 6019 6020Syntax: 6021 6022@example 6023pragma Overriding_Renamings; 6024@end example 6025 6026This is a GNAT configuration pragma to simplify porting 6027legacy code accepted by the Rational 6028Ada compiler. In the presence of this pragma, a renaming declaration that 6029renames an inherited operation declared in the same scope is legal if selected 6030notation is used as in: 6031 6032@example 6033pragma Overriding_Renamings; 6034... 6035package R is 6036 function F (..); 6037 ... 6038 function F (..) renames R.F; 6039end R; 6040@end example 6041 6042even though 6043RM 8.3 (15) stipulates that an overridden operation is not visible within the 6044declaration of the overriding operation. 6045 6046@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 6047@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b5} 6048@section Pragma Partition_Elaboration_Policy 6049 6050 6051Syntax: 6052 6053@example 6054pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 6055 6056POLICY_IDENTIFIER ::= Concurrent | Sequential 6057@end example 6058 6059This pragma is standard in Ada 2005, but is available in all earlier 6060versions of Ada as an implementation-defined pragma. 6061See Ada 2012 Reference Manual for details. 6062 6063@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 6064@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b6}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b7} 6065@section Pragma Part_Of 6066 6067 6068Syntax: 6069 6070@example 6071pragma Part_Of (ABSTRACT_STATE); 6072 6073ABSTRACT_STATE ::= NAME 6074@end example 6075 6076For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the 6077SPARK 2014 Reference Manual, section 7.2.6. 6078 6079@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 6080@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b8} 6081@section Pragma Passive 6082 6083 6084Syntax: 6085 6086@example 6087pragma Passive [(Semaphore | No)]; 6088@end example 6089 6090Syntax checked, but otherwise ignored by GNAT. This is recognized for 6091compatibility with DEC Ada 83 implementations, where it is used within a 6092task definition to request that a task be made passive. If the argument 6093@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 6094treats the pragma as an assertion that the containing task is passive 6095and that optimization of context switch with this task is permitted and 6096desired. If the argument @code{No} is present, the task must not be 6097optimized. GNAT does not attempt to optimize any tasks in this manner 6098(since protected objects are available in place of passive tasks). 6099 6100For more information on the subject of passive tasks, see the section 6101'Passive Task Optimization' in the GNAT Users Guide. 6102 6103@node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas 6104@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b9}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{ba} 6105@section Pragma Persistent_BSS 6106 6107 6108Syntax: 6109 6110@example 6111pragma Persistent_BSS [(LOCAL_NAME)] 6112@end example 6113 6114This pragma allows selected objects to be placed in the @code{.persistent_bss} 6115section. On some targets the linker and loader provide for special 6116treatment of this section, allowing a program to be reloaded without 6117affecting the contents of this data (hence the name persistent). 6118 6119There are two forms of usage. If an argument is given, it must be the 6120local name of a library-level object, with no explicit initialization 6121and whose type is potentially persistent. If no argument is given, then 6122the pragma is a configuration pragma, and applies to all library-level 6123objects with no explicit initialization of potentially persistent types. 6124 6125A potentially persistent type is a scalar type, or an untagged, 6126non-discriminated record, all of whose components have no explicit 6127initialization and are themselves of a potentially persistent type, 6128or an array, all of whose constraints are static, and whose component 6129type is potentially persistent. 6130 6131If this pragma is used on a target where this feature is not supported, 6132then the pragma will be ignored. See also @code{pragma Linker_Section}. 6133 6134@node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas 6135@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{bb} 6136@section Pragma Polling 6137 6138 6139Syntax: 6140 6141@example 6142pragma Polling (ON | OFF); 6143@end example 6144 6145This pragma controls the generation of polling code. This is normally off. 6146If @code{pragma Polling (ON)} is used then periodic calls are generated to 6147the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 6148runtime library, and can be found in file @code{a-excpol.adb}. 6149 6150Pragma @code{Polling} can appear as a configuration pragma (for example it 6151can be placed in the @code{gnat.adc} file) to enable polling globally, or it 6152can be used in the statement or declaration sequence to control polling 6153more locally. 6154 6155A call to the polling routine is generated at the start of every loop and 6156at the start of every subprogram call. This guarantees that the @code{Poll} 6157routine is called frequently, and places an upper bound (determined by 6158the complexity of the code) on the period between two @code{Poll} calls. 6159 6160The primary purpose of the polling interface is to enable asynchronous 6161aborts on targets that cannot otherwise support it (for example Windows 6162NT), but it may be used for any other purpose requiring periodic polling. 6163The standard version is null, and can be replaced by a user program. This 6164will require re-compilation of the @code{Ada.Exceptions} package that can 6165be found in files @code{a-except.ads} and @code{a-except.adb}. 6166 6167A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT 6168distribution) is used to enable the asynchronous abort capability on 6169targets that do not normally support the capability. The version of 6170@code{Poll} in this file makes a call to the appropriate runtime routine 6171to test for an abort condition. 6172 6173Note that polling can also be enabled by use of the @emph{-gnatP} switch. 6174See the section on switches for gcc in the @cite{GNAT User's Guide}. 6175 6176@node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas 6177@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{bc} 6178@section Pragma Post 6179 6180 6181@geindex Post 6182 6183@geindex Checks 6184@geindex postconditions 6185 6186Syntax: 6187 6188@example 6189pragma Post (Boolean_Expression); 6190@end example 6191 6192The @code{Post} pragma is intended to be an exact replacement for 6193the language-defined 6194@code{Post} aspect, and shares its restrictions and semantics. 6195It must appear either immediately following the corresponding 6196subprogram declaration (only other pragmas may intervene), or 6197if there is no separate subprogram declaration, then it can 6198appear at the start of the declarations in a subprogram body 6199(preceded only by other pragmas). 6200 6201@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 6202@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{bd} 6203@section Pragma Postcondition 6204 6205 6206@geindex Postcondition 6207 6208@geindex Checks 6209@geindex postconditions 6210 6211Syntax: 6212 6213@example 6214pragma Postcondition ( 6215 [Check =>] Boolean_Expression 6216 [,[Message =>] String_Expression]); 6217@end example 6218 6219The @code{Postcondition} pragma allows specification of automatic 6220postcondition checks for subprograms. These checks are similar to 6221assertions, but are automatically inserted just prior to the return 6222statements of the subprogram with which they are associated (including 6223implicit returns at the end of procedure bodies and associated 6224exception handlers). 6225 6226In addition, the boolean expression which is the condition which 6227must be true may contain references to function'Result in the case 6228of a function to refer to the returned value. 6229 6230@code{Postcondition} pragmas may appear either immediately following the 6231(separate) declaration of a subprogram, or at the start of the 6232declarations of a subprogram body. Only other pragmas may intervene 6233(that is appear between the subprogram declaration and its 6234postconditions, or appear before the postcondition in the 6235declaration sequence in a subprogram body). In the case of a 6236postcondition appearing after a subprogram declaration, the 6237formal arguments of the subprogram are visible, and can be 6238referenced in the postcondition expressions. 6239 6240The postconditions are collected and automatically tested just 6241before any return (implicit or explicit) in the subprogram body. 6242A postcondition is only recognized if postconditions are active 6243at the time the pragma is encountered. The compiler switch @emph{gnata} 6244turns on all postconditions by default, and pragma @code{Check_Policy} 6245with an identifier of @code{Postcondition} can also be used to 6246control whether postconditions are active. 6247 6248The general approach is that postconditions are placed in the spec 6249if they represent functional aspects which make sense to the client. 6250For example we might have: 6251 6252@example 6253function Direction return Integer; 6254pragma Postcondition 6255 (Direction'Result = +1 6256 or else 6257 Direction'Result = -1); 6258@end example 6259 6260which serves to document that the result must be +1 or -1, and 6261will test that this is the case at run time if postcondition 6262checking is active. 6263 6264Postconditions within the subprogram body can be used to 6265check that some internal aspect of the implementation, 6266not visible to the client, is operating as expected. 6267For instance if a square root routine keeps an internal 6268counter of the number of times it is called, then we 6269might have the following postcondition: 6270 6271@example 6272Sqrt_Calls : Natural := 0; 6273 6274function Sqrt (Arg : Float) return Float is 6275 pragma Postcondition 6276 (Sqrt_Calls = Sqrt_Calls'Old + 1); 6277 ... 6278end Sqrt 6279@end example 6280 6281As this example, shows, the use of the @code{Old} attribute 6282is often useful in postconditions to refer to the state on 6283entry to the subprogram. 6284 6285Note that postconditions are only checked on normal returns 6286from the subprogram. If an abnormal return results from 6287raising an exception, then the postconditions are not checked. 6288 6289If a postcondition fails, then the exception 6290@code{System.Assertions.Assert_Failure} is raised. If 6291a message argument was supplied, then the given string 6292will be used as the exception message. If no message 6293argument was supplied, then the default message has 6294the form "Postcondition failed at file_name:line". The 6295exception is raised in the context of the subprogram 6296body, so it is possible to catch postcondition failures 6297within the subprogram body itself. 6298 6299Within a package spec, normal visibility rules 6300in Ada would prevent forward references within a 6301postcondition pragma to functions defined later in 6302the same package. This would introduce undesirable 6303ordering constraints. To avoid this problem, all 6304postcondition pragmas are analyzed at the end of 6305the package spec, allowing forward references. 6306 6307The following example shows that this even allows 6308mutually recursive postconditions as in: 6309 6310@example 6311package Parity_Functions is 6312 function Odd (X : Natural) return Boolean; 6313 pragma Postcondition 6314 (Odd'Result = 6315 (x = 1 6316 or else 6317 (x /= 0 and then Even (X - 1)))); 6318 6319 function Even (X : Natural) return Boolean; 6320 pragma Postcondition 6321 (Even'Result = 6322 (x = 0 6323 or else 6324 (x /= 1 and then Odd (X - 1)))); 6325 6326end Parity_Functions; 6327@end example 6328 6329There are no restrictions on the complexity or form of 6330conditions used within @code{Postcondition} pragmas. 6331The following example shows that it is even possible 6332to verify performance behavior. 6333 6334@example 6335package Sort is 6336 6337 Performance : constant Float; 6338 -- Performance constant set by implementation 6339 -- to match target architecture behavior. 6340 6341 procedure Treesort (Arg : String); 6342 -- Sorts characters of argument using N*logN sort 6343 pragma Postcondition 6344 (Float (Clock - Clock'Old) <= 6345 Float (Arg'Length) * 6346 log (Float (Arg'Length)) * 6347 Performance); 6348end Sort; 6349@end example 6350 6351Note: postcondition pragmas associated with subprograms that are 6352marked as Inline_Always, or those marked as Inline with front-end 6353inlining (-gnatN option set) are accepted and legality-checked 6354by the compiler, but are ignored at run-time even if postcondition 6355checking is enabled. 6356 6357Note that pragma @code{Postcondition} differs from the language-defined 6358@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 6359multiple occurrences, allowing occurences in the body even if there 6360is a separate spec, and allowing a second string parameter, and the 6361use of the pragma identifier @code{Check}. Historically, pragma 6362@code{Postcondition} was implemented prior to the development of 6363Ada 2012, and has been retained in its original form for 6364compatibility purposes. 6365 6366@node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas 6367@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{be} 6368@section Pragma Post_Class 6369 6370 6371@geindex Post 6372 6373@geindex Checks 6374@geindex postconditions 6375 6376Syntax: 6377 6378@example 6379pragma Post_Class (Boolean_Expression); 6380@end example 6381 6382The @code{Post_Class} pragma is intended to be an exact replacement for 6383the language-defined 6384@code{Post'Class} aspect, and shares its restrictions and semantics. 6385It must appear either immediately following the corresponding 6386subprogram declaration (only other pragmas may intervene), or 6387if there is no separate subprogram declaration, then it can 6388appear at the start of the declarations in a subprogram body 6389(preceded only by other pragmas). 6390 6391Note: This pragma is called @code{Post_Class} rather than 6392@code{Post'Class} because the latter would not be strictly 6393conforming to the allowed syntax for pragmas. The motivation 6394for provinding pragmas equivalent to the aspects is to allow a program 6395to be written using the pragmas, and then compiled if necessary 6396using an Ada compiler that does not recognize the pragmas or 6397aspects, but is prepared to ignore the pragmas. The assertion 6398policy that controls this pragma is @code{Post'Class}, not 6399@code{Post_Class}. 6400 6401@node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas 6402@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{bf} 6403@section Pragma Rename_Pragma 6404 6405 6406@geindex Pragmas 6407@geindex synonyms 6408 6409Syntax: 6410 6411@example 6412pragma Rename_Pragma ( 6413 [New_Name =>] IDENTIFIER, 6414 [Renamed =>] pragma_IDENTIFIER); 6415@end example 6416 6417This pragma provides a mechanism for supplying new names for existing 6418pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for 6419the Renamed pragma. For example, suppose you have code that was originally 6420developed on a compiler that supports Inline_Only as an implementation defined 6421pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 6422least very similar to) the GNAT implementation defined pragma 6423Inline_Always. You could globally replace Inline_Only with Inline_Always. 6424 6425However, to avoid that source modification, you could instead add a 6426configuration pragma: 6427 6428@example 6429pragma Rename_Pragma ( 6430 New_Name => Inline_Only, 6431 Renamed => Inline_Always); 6432@end example 6433 6434Then GNAT will treat "pragma Inline_Only ..." as if you had written 6435"pragma Inline_Always ...". 6436 6437Pragma Inline_Only will not necessarily mean the same thing as the other Ada 6438compiler; it's up to you to make sure the semantics are close enough. 6439 6440@node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas 6441@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{c0} 6442@section Pragma Pre 6443 6444 6445@geindex Pre 6446 6447@geindex Checks 6448@geindex preconditions 6449 6450Syntax: 6451 6452@example 6453pragma Pre (Boolean_Expression); 6454@end example 6455 6456The @code{Pre} pragma is intended to be an exact replacement for 6457the language-defined 6458@code{Pre} aspect, and shares its restrictions and semantics. 6459It must appear either immediately following the corresponding 6460subprogram declaration (only other pragmas may intervene), or 6461if there is no separate subprogram declaration, then it can 6462appear at the start of the declarations in a subprogram body 6463(preceded only by other pragmas). 6464 6465@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 6466@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{c1} 6467@section Pragma Precondition 6468 6469 6470@geindex Preconditions 6471 6472@geindex Checks 6473@geindex preconditions 6474 6475Syntax: 6476 6477@example 6478pragma Precondition ( 6479 [Check =>] Boolean_Expression 6480 [,[Message =>] String_Expression]); 6481@end example 6482 6483The @code{Precondition} pragma is similar to @code{Postcondition} 6484except that the corresponding checks take place immediately upon 6485entry to the subprogram, and if a precondition fails, the exception 6486is raised in the context of the caller, and the attribute 'Result 6487cannot be used within the precondition expression. 6488 6489Otherwise, the placement and visibility rules are identical to those 6490described for postconditions. The following is an example of use 6491within a package spec: 6492 6493@example 6494package Math_Functions is 6495 ... 6496 function Sqrt (Arg : Float) return Float; 6497 pragma Precondition (Arg >= 0.0) 6498 ... 6499end Math_Functions; 6500@end example 6501 6502@code{Precondition} pragmas may appear either immediately following the 6503(separate) declaration of a subprogram, or at the start of the 6504declarations of a subprogram body. Only other pragmas may intervene 6505(that is appear between the subprogram declaration and its 6506postconditions, or appear before the postcondition in the 6507declaration sequence in a subprogram body). 6508 6509Note: precondition pragmas associated with subprograms that are 6510marked as Inline_Always, or those marked as Inline with front-end 6511inlining (-gnatN option set) are accepted and legality-checked 6512by the compiler, but are ignored at run-time even if precondition 6513checking is enabled. 6514 6515Note that pragma @code{Precondition} differs from the language-defined 6516@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 6517multiple occurrences, allowing occurences in the body even if there 6518is a separate spec, and allowing a second string parameter, and the 6519use of the pragma identifier @code{Check}. Historically, pragma 6520@code{Precondition} was implemented prior to the development of 6521Ada 2012, and has been retained in its original form for 6522compatibility purposes. 6523 6524@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 6525@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c2}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{c3} 6526@section Pragma Predicate 6527 6528 6529Syntax: 6530 6531@example 6532pragma Predicate 6533 ([Entity =>] type_LOCAL_NAME, 6534 [Check =>] EXPRESSION); 6535@end example 6536 6537This pragma (available in all versions of Ada in GNAT) encompasses both 6538the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 6539Ada 2012. A predicate is regarded as static if it has an allowed form 6540for @code{Static_Predicate} and is otherwise treated as a 6541@code{Dynamic_Predicate}. Otherwise, predicates specified by this 6542pragma behave exactly as described in the Ada 2012 reference manual. 6543For example, if we have 6544 6545@example 6546type R is range 1 .. 10; 6547subtype S is R; 6548pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6549subtype Q is R 6550pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6551@end example 6552 6553the effect is identical to the following Ada 2012 code: 6554 6555@example 6556type R is range 1 .. 10; 6557subtype S is R with 6558 Static_Predicate => S not in 4 .. 6; 6559subtype Q is R with 6560 Dynamic_Predicate => F(Q) or G(Q); 6561@end example 6562 6563Note that there are no pragmas @code{Dynamic_Predicate} 6564or @code{Static_Predicate}. That is 6565because these pragmas would affect legality and semantics of 6566the program and thus do not have a neutral effect if ignored. 6567The motivation behind providing pragmas equivalent to 6568corresponding aspects is to allow a program to be written 6569using the pragmas, and then compiled with a compiler that 6570will ignore the pragmas. That doesn't work in the case of 6571static and dynamic predicates, since if the corresponding 6572pragmas are ignored, then the behavior of the program is 6573fundamentally changed (for example a membership test 6574@code{A in B} would not take into account a predicate 6575defined for subtype B). When following this approach, the 6576use of predicates should be avoided. 6577 6578@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6579@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c4} 6580@section Pragma Predicate_Failure 6581 6582 6583Syntax: 6584 6585@example 6586pragma Predicate_Failure 6587 ([Entity =>] type_LOCAL_NAME, 6588 [Message =>] String_Expression); 6589@end example 6590 6591The @code{Predicate_Failure} pragma is intended to be an exact replacement for 6592the language-defined 6593@code{Predicate_Failure} aspect, and shares its restrictions and semantics. 6594 6595@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6596@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c5} 6597@section Pragma Preelaborable_Initialization 6598 6599 6600Syntax: 6601 6602@example 6603pragma Preelaborable_Initialization (DIRECT_NAME); 6604@end example 6605 6606This pragma is standard in Ada 2005, but is available in all earlier 6607versions of Ada as an implementation-defined pragma. 6608See Ada 2012 Reference Manual for details. 6609 6610@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6611@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c6} 6612@section Pragma Prefix_Exception_Messages 6613 6614 6615@geindex Prefix_Exception_Messages 6616 6617@geindex exception 6618 6619@geindex Exception_Message 6620 6621Syntax: 6622 6623@example 6624pragma Prefix_Exception_Messages; 6625@end example 6626 6627This is an implementation-defined configuration pragma that affects the 6628behavior of raise statements with a message given as a static string 6629constant (typically a string literal). In such cases, the string will 6630be automatically prefixed by the name of the enclosing entity (giving 6631the package and subprogram containing the raise statement). This helps 6632to identify where messages are coming from, and this mode is automatic 6633for the run-time library. 6634 6635The pragma has no effect if the message is computed with an expression other 6636than a static string constant, since the assumption in this case is that 6637the program computes exactly the string it wants. If you still want the 6638prefixing in this case, you can always call 6639@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6640 6641@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6642@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c7} 6643@section Pragma Pre_Class 6644 6645 6646@geindex Pre_Class 6647 6648@geindex Checks 6649@geindex preconditions 6650 6651Syntax: 6652 6653@example 6654pragma Pre_Class (Boolean_Expression); 6655@end example 6656 6657The @code{Pre_Class} pragma is intended to be an exact replacement for 6658the language-defined 6659@code{Pre'Class} aspect, and shares its restrictions and semantics. 6660It must appear either immediately following the corresponding 6661subprogram declaration (only other pragmas may intervene), or 6662if there is no separate subprogram declaration, then it can 6663appear at the start of the declarations in a subprogram body 6664(preceded only by other pragmas). 6665 6666Note: This pragma is called @code{Pre_Class} rather than 6667@code{Pre'Class} because the latter would not be strictly 6668conforming to the allowed syntax for pragmas. The motivation 6669for providing pragmas equivalent to the aspects is to allow a program 6670to be written using the pragmas, and then compiled if necessary 6671using an Ada compiler that does not recognize the pragmas or 6672aspects, but is prepared to ignore the pragmas. The assertion 6673policy that controls this pragma is @code{Pre'Class}, not 6674@code{Pre_Class}. 6675 6676@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6677@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c8} 6678@section Pragma Priority_Specific_Dispatching 6679 6680 6681Syntax: 6682 6683@example 6684pragma Priority_Specific_Dispatching ( 6685 POLICY_IDENTIFIER, 6686 first_priority_EXPRESSION, 6687 last_priority_EXPRESSION) 6688 6689POLICY_IDENTIFIER ::= 6690 EDF_Across_Priorities | 6691 FIFO_Within_Priorities | 6692 Non_Preemptive_Within_Priorities | 6693 Round_Robin_Within_Priorities 6694@end example 6695 6696This pragma is standard in Ada 2005, but is available in all earlier 6697versions of Ada as an implementation-defined pragma. 6698See Ada 2012 Reference Manual for details. 6699 6700@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6701@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c9} 6702@section Pragma Profile 6703 6704 6705Syntax: 6706 6707@example 6708pragma Profile (Ravenscar | Restricted | Rational | 6709 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 6710@end example 6711 6712This pragma is standard in Ada 2005, but is available in all earlier 6713versions of Ada as an implementation-defined pragma. This is a 6714configuration pragma that establishes a set of configuration pragmas 6715that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 6716The other possibilities (@code{Restricted}, @code{Rational}, 6717@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) 6718are implementation-defined. The set of configuration pragmas 6719is defined in the following sections. 6720 6721 6722@itemize * 6723 6724@item 6725Pragma Profile (Ravenscar) 6726 6727The @code{Ravenscar} profile is standard in Ada 2005, 6728but is available in all earlier 6729versions of Ada as an implementation-defined pragma. This profile 6730establishes the following set of configuration pragmas: 6731 6732 6733@itemize * 6734 6735@item 6736@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6737 6738[RM D.2.2] Tasks are dispatched following a preemptive 6739priority-ordered scheduling policy. 6740 6741@item 6742@code{Locking_Policy (Ceiling_Locking)} 6743 6744[RM D.3] While tasks and interrupts execute a protected action, they inherit 6745the ceiling priority of the corresponding protected object. 6746 6747@item 6748@code{Detect_Blocking} 6749 6750This pragma forces the detection of potentially blocking operations within a 6751protected operation, and to raise Program_Error if that happens. 6752@end itemize 6753 6754plus the following set of restrictions: 6755 6756 6757@itemize * 6758 6759@item 6760@code{Max_Entry_Queue_Length => 1} 6761 6762No task can be queued on a protected entry. 6763 6764@item 6765@code{Max_Protected_Entries => 1} 6766 6767@item 6768@code{Max_Task_Entries => 0} 6769 6770No rendezvous statements are allowed. 6771 6772@item 6773@code{No_Abort_Statements} 6774 6775@item 6776@code{No_Dynamic_Attachment} 6777 6778@item 6779@code{No_Dynamic_Priorities} 6780 6781@item 6782@code{No_Implicit_Heap_Allocations} 6783 6784@item 6785@code{No_Local_Protected_Objects} 6786 6787@item 6788@code{No_Local_Timing_Events} 6789 6790@item 6791@code{No_Protected_Type_Allocators} 6792 6793@item 6794@code{No_Relative_Delay} 6795 6796@item 6797@code{No_Requeue_Statements} 6798 6799@item 6800@code{No_Select_Statements} 6801 6802@item 6803@code{No_Specific_Termination_Handlers} 6804 6805@item 6806@code{No_Task_Allocators} 6807 6808@item 6809@code{No_Task_Hierarchy} 6810 6811@item 6812@code{No_Task_Termination} 6813 6814@item 6815@code{Simple_Barriers} 6816@end itemize 6817 6818The Ravenscar profile also includes the following restrictions that specify 6819that there are no semantic dependences on the corresponding predefined 6820packages: 6821 6822 6823@itemize * 6824 6825@item 6826@code{No_Dependence => Ada.Asynchronous_Task_Control} 6827 6828@item 6829@code{No_Dependence => Ada.Calendar} 6830 6831@item 6832@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6833 6834@item 6835@code{No_Dependence => Ada.Execution_Time.Timers} 6836 6837@item 6838@code{No_Dependence => Ada.Task_Attributes} 6839 6840@item 6841@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6842@end itemize 6843 6844This set of configuration pragmas and restrictions correspond to the 6845definition of the 'Ravenscar Profile' for limited tasking, devised and 6846published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6847A description is also available at 6848@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6849 6850The original definition of the profile was revised at subsequent IRTAW 6851meetings. It has been included in the ISO 6852@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6853and was made part of the Ada 2005 standard. 6854The formal definition given by 6855the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6856AI-305) available at 6857@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6858@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6859 6860The above set is a superset of the restrictions provided by pragma 6861@code{Profile (Restricted)}, it includes six additional restrictions 6862(@code{Simple_Barriers}, @code{No_Select_Statements}, 6863@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6864@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6865that pragma @code{Profile (Ravenscar)}, like the pragma 6866@code{Profile (Restricted)}, 6867automatically causes the use of a simplified, 6868more efficient version of the tasking run-time library. 6869 6870@item 6871Pragma Profile (GNAT_Extended_Ravenscar) 6872 6873This profile corresponds to a GNAT specific extension of the 6874Ravenscar profile. The profile may change in the future although 6875only in a compatible way: some restrictions may be removed or 6876relaxed. It is defined as a variation of the Ravenscar profile. 6877 6878The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6879by @code{No_Implicit_Task_Allocations} and 6880@code{No_Implicit_Protected_Object_Allocations}. 6881 6882The @code{Simple_Barriers} restriction has been replaced by 6883@code{Pure_Barriers}. 6884 6885The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and 6886@code{No_Relative_Delay} restrictions have been removed. 6887 6888@item 6889Pragma Profile (GNAT_Ravenscar_EDF) 6890 6891This profile corresponds to the Ravenscar profile but using 6892EDF_Across_Priority as the Task_Scheduling_Policy. 6893 6894@item 6895Pragma Profile (Restricted) 6896 6897This profile corresponds to the GNAT restricted run time. It 6898establishes the following set of restrictions: 6899 6900 6901@itemize * 6902 6903@item 6904@code{No_Abort_Statements} 6905 6906@item 6907@code{No_Entry_Queue} 6908 6909@item 6910@code{No_Task_Hierarchy} 6911 6912@item 6913@code{No_Task_Allocators} 6914 6915@item 6916@code{No_Dynamic_Priorities} 6917 6918@item 6919@code{No_Terminate_Alternatives} 6920 6921@item 6922@code{No_Dynamic_Attachment} 6923 6924@item 6925@code{No_Protected_Type_Allocators} 6926 6927@item 6928@code{No_Local_Protected_Objects} 6929 6930@item 6931@code{No_Requeue_Statements} 6932 6933@item 6934@code{No_Task_Attributes_Package} 6935 6936@item 6937@code{Max_Asynchronous_Select_Nesting = 0} 6938 6939@item 6940@code{Max_Task_Entries = 0} 6941 6942@item 6943@code{Max_Protected_Entries = 1} 6944 6945@item 6946@code{Max_Select_Alternatives = 0} 6947@end itemize 6948 6949This set of restrictions causes the automatic selection of a simplified 6950version of the run time that provides improved performance for the 6951limited set of tasking functionality permitted by this set of restrictions. 6952 6953@item 6954Pragma Profile (Rational) 6955 6956The Rational profile is intended to facilitate porting legacy code that 6957compiles with the Rational APEX compiler, even when the code includes non- 6958conforming Ada constructs. The profile enables the following three pragmas: 6959 6960 6961@itemize * 6962 6963@item 6964@code{pragma Implicit_Packing} 6965 6966@item 6967@code{pragma Overriding_Renamings} 6968 6969@item 6970@code{pragma Use_VADS_Size} 6971@end itemize 6972@end itemize 6973 6974@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6975@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{ca} 6976@section Pragma Profile_Warnings 6977 6978 6979Syntax: 6980 6981@example 6982pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6983@end example 6984 6985This is an implementation-defined pragma that is similar in 6986effect to @code{pragma Profile} except that instead of 6987generating @code{Restrictions} pragmas, it generates 6988@code{Restriction_Warnings} pragmas. The result is that 6989violations of the profile generate warning messages instead 6990of error messages. 6991 6992@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 6993@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{cb} 6994@section Pragma Propagate_Exceptions 6995 6996 6997@geindex Interfacing to C++ 6998 6999Syntax: 7000 7001@example 7002pragma Propagate_Exceptions; 7003@end example 7004 7005This pragma is now obsolete and, other than generating a warning if warnings 7006on obsolescent features are enabled, is ignored. 7007It is retained for compatibility 7008purposes. It used to be used in connection with optimization of 7009a now-obsolete mechanism for implementation of exceptions. 7010 7011@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 7012@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{cc} 7013@section Pragma Provide_Shift_Operators 7014 7015 7016@geindex Shift operators 7017 7018Syntax: 7019 7020@example 7021pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 7022@end example 7023 7024This pragma can be applied to a first subtype local name that specifies 7025either an unsigned or signed type. It has the effect of providing the 7026five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 7027Rotate_Left and Rotate_Right) for the given type. It is similar to 7028including the function declarations for these five operators, together 7029with the pragma Import (Intrinsic, ...) statements. 7030 7031@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 7032@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{cd} 7033@section Pragma Psect_Object 7034 7035 7036Syntax: 7037 7038@example 7039pragma Psect_Object ( 7040 [Internal =>] LOCAL_NAME, 7041 [, [External =>] EXTERNAL_SYMBOL] 7042 [, [Size =>] EXTERNAL_SYMBOL]); 7043 7044EXTERNAL_SYMBOL ::= 7045 IDENTIFIER 7046| static_string_EXPRESSION 7047@end example 7048 7049This pragma is identical in effect to pragma @code{Common_Object}. 7050 7051@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 7052@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{cf} 7053@section Pragma Pure_Function 7054 7055 7056Syntax: 7057 7058@example 7059pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 7060@end example 7061 7062This pragma appears in the same declarative part as a function 7063declaration (or a set of function declarations if more than one 7064overloaded declaration exists, in which case the pragma applies 7065to all entities). It specifies that the function @code{Entity} is 7066to be considered pure for the purposes of code generation. This means 7067that the compiler can assume that there are no side effects, and 7068in particular that two calls with identical arguments produce the 7069same result. It also means that the function can be used in an 7070address clause. 7071 7072Note that, quite deliberately, there are no static checks to try 7073to ensure that this promise is met, so @code{Pure_Function} can be used 7074with functions that are conceptually pure, even if they do modify 7075global variables. For example, a square root function that is 7076instrumented to count the number of times it is called is still 7077conceptually pure, and can still be optimized, even though it 7078modifies a global variable (the count). Memo functions are another 7079example (where a table of previous calls is kept and consulted to 7080avoid re-computation). 7081 7082Note also that the normal rules excluding optimization of subprograms 7083in pure units (when parameter types are descended from System.Address, 7084or when the full view of a parameter type is limited), do not apply 7085for the Pure_Function case. If you explicitly specify Pure_Function, 7086the compiler may optimize away calls with identical arguments, and 7087if that results in unexpected behavior, the proper action is not to 7088use the pragma for subprograms that are not (conceptually) pure. 7089 7090Note: Most functions in a @code{Pure} package are automatically pure, and 7091there is no need to use pragma @code{Pure_Function} for such functions. One 7092exception is any function that has at least one formal of type 7093@code{System.Address} or a type derived from it. Such functions are not 7094considered pure by default, since the compiler assumes that the 7095@code{Address} parameter may be functioning as a pointer and that the 7096referenced data may change even if the address value does not. 7097Similarly, imported functions are not considered to be pure by default, 7098since there is no way of checking that they are in fact pure. The use 7099of pragma @code{Pure_Function} for such a function will override these default 7100assumption, and cause the compiler to treat a designated subprogram as pure 7101in these cases. 7102 7103Note: If pragma @code{Pure_Function} is applied to a renamed function, it 7104applies to the underlying renamed function. This can be used to 7105disambiguate cases of overloading where some but not all functions 7106in a set of overloaded functions are to be designated as pure. 7107 7108If pragma @code{Pure_Function} is applied to a library-level function, the 7109function is also considered pure from an optimization point of view, but the 7110unit is not a Pure unit in the categorization sense. So for example, a function 7111thus marked is free to @code{with} non-pure units. 7112 7113@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 7114@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{d0} 7115@section Pragma Rational 7116 7117 7118Syntax: 7119 7120@example 7121pragma Rational; 7122@end example 7123 7124This pragma is considered obsolescent, but is retained for 7125compatibility purposes. It is equivalent to: 7126 7127@example 7128pragma Profile (Rational); 7129@end example 7130 7131@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 7132@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{d1} 7133@section Pragma Ravenscar 7134 7135 7136Syntax: 7137 7138@example 7139pragma Ravenscar; 7140@end example 7141 7142This pragma is considered obsolescent, but is retained for 7143compatibility purposes. It is equivalent to: 7144 7145@example 7146pragma Profile (Ravenscar); 7147@end example 7148 7149which is the preferred method of setting the @code{Ravenscar} profile. 7150 7151@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 7152@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{d3} 7153@section Pragma Refined_Depends 7154 7155 7156Syntax: 7157 7158@example 7159pragma Refined_Depends (DEPENDENCY_RELATION); 7160 7161DEPENDENCY_RELATION ::= 7162 null 7163 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 7164 7165DEPENDENCY_CLAUSE ::= 7166 OUTPUT_LIST =>[+] INPUT_LIST 7167 | NULL_DEPENDENCY_CLAUSE 7168 7169NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 7170 7171OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 7172 7173INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 7174 7175OUTPUT ::= NAME | FUNCTION_RESULT 7176INPUT ::= NAME 7177 7178where FUNCTION_RESULT is a function Result attribute_reference 7179@end example 7180 7181For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in 7182the SPARK 2014 Reference Manual, section 6.1.5. 7183 7184@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 7185@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d4}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d5} 7186@section Pragma Refined_Global 7187 7188 7189Syntax: 7190 7191@example 7192pragma Refined_Global (GLOBAL_SPECIFICATION); 7193 7194GLOBAL_SPECIFICATION ::= 7195 null 7196 | (GLOBAL_LIST) 7197 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 7198 7199MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 7200 7201MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 7202GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 7203GLOBAL_ITEM ::= NAME 7204@end example 7205 7206For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in 7207the SPARK 2014 Reference Manual, section 6.1.4. 7208 7209@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 7210@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d6}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d7} 7211@section Pragma Refined_Post 7212 7213 7214Syntax: 7215 7216@example 7217pragma Refined_Post (boolean_EXPRESSION); 7218@end example 7219 7220For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in 7221the SPARK 2014 Reference Manual, section 7.2.7. 7222 7223@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 7224@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d8}@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d9} 7225@section Pragma Refined_State 7226 7227 7228Syntax: 7229 7230@example 7231pragma Refined_State (REFINEMENT_LIST); 7232 7233REFINEMENT_LIST ::= 7234 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 7235 7236REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 7237 7238CONSTITUENT_LIST ::= 7239 null 7240 | CONSTITUENT 7241 | (CONSTITUENT @{, CONSTITUENT@}) 7242 7243CONSTITUENT ::= object_NAME | state_NAME 7244@end example 7245 7246For the semantics of this pragma, see the entry for aspect @code{Refined_State} in 7247the SPARK 2014 Reference Manual, section 7.2.2. 7248 7249@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 7250@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{da} 7251@section Pragma Relative_Deadline 7252 7253 7254Syntax: 7255 7256@example 7257pragma Relative_Deadline (time_span_EXPRESSION); 7258@end example 7259 7260This pragma is standard in Ada 2005, but is available in all earlier 7261versions of Ada as an implementation-defined pragma. 7262See Ada 2012 Reference Manual for details. 7263 7264@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas 7265@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{db}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{dc} 7266@section Pragma Remote_Access_Type 7267 7268 7269Syntax: 7270 7271@example 7272pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 7273@end example 7274 7275This pragma appears in the formal part of a generic declaration. 7276It specifies an exception to the RM rule from E.2.2(17/2), which forbids 7277the use of a remote access to class-wide type as actual for a formal 7278access type. 7279 7280When this pragma applies to a formal access type @code{Entity}, that 7281type is treated as a remote access to class-wide type in the generic. 7282It must be a formal general access type, and its designated type must 7283be the class-wide type of a formal tagged limited private type from the 7284same generic declaration. 7285 7286In the generic unit, the formal type is subject to all restrictions 7287pertaining to remote access to class-wide types. At instantiation, the 7288actual type must be a remote access to class-wide type. 7289 7290@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas 7291@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{dd} 7292@section Pragma Restricted_Run_Time 7293 7294 7295Syntax: 7296 7297@example 7298pragma Restricted_Run_Time; 7299@end example 7300 7301This pragma is considered obsolescent, but is retained for 7302compatibility purposes. It is equivalent to: 7303 7304@example 7305pragma Profile (Restricted); 7306@end example 7307 7308which is the preferred method of setting the restricted run time 7309profile. 7310 7311@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 7312@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{de} 7313@section Pragma Restriction_Warnings 7314 7315 7316Syntax: 7317 7318@example 7319pragma Restriction_Warnings 7320 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 7321@end example 7322 7323This pragma allows a series of restriction identifiers to be 7324specified (the list of allowed identifiers is the same as for 7325pragma @code{Restrictions}). For each of these identifiers 7326the compiler checks for violations of the restriction, but 7327generates a warning message rather than an error message 7328if the restriction is violated. 7329 7330One use of this is in situations where you want to know 7331about violations of a restriction, but you want to ignore some of 7332these violations. Consider this example, where you want to set 7333Ada_95 mode and enable style checks, but you want to know about 7334any other use of implementation pragmas: 7335 7336@example 7337pragma Restriction_Warnings (No_Implementation_Pragmas); 7338pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 7339pragma Ada_95; 7340pragma Style_Checks ("2bfhkM160"); 7341pragma Warnings (On, "violation of No_Implementation_Pragmas"); 7342@end example 7343 7344By including the above lines in a configuration pragmas file, 7345the Ada_95 and Style_Checks pragmas are accepted without 7346generating a warning, but any other use of implementation 7347defined pragmas will cause a warning to be generated. 7348 7349@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas 7350@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{df} 7351@section Pragma Reviewable 7352 7353 7354Syntax: 7355 7356@example 7357pragma Reviewable; 7358@end example 7359 7360This pragma is an RM-defined standard pragma, but has no effect on the 7361program being compiled, or on the code generated for the program. 7362 7363To obtain the required output specified in RM H.3.1, the compiler must be 7364run with various special switches as follows: 7365 7366 7367@itemize * 7368 7369@item 7370@emph{Where compiler-generated run-time checks remain} 7371 7372The switch @emph{-gnatGL} 7373may be used to list the expanded code in pseudo-Ada form. 7374Runtime checks show up in the listing either as explicit 7375checks or operators marked with @{@} to indicate a check is present. 7376 7377@item 7378@emph{An identification of known exceptions at compile time} 7379 7380If the program is compiled with @emph{-gnatwa}, 7381the compiler warning messages will indicate all cases where the compiler 7382detects that an exception is certain to occur at run time. 7383 7384@item 7385@emph{Possible reads of uninitialized variables} 7386 7387The compiler warns of many such cases, but its output is incomplete. 7388@end itemize 7389 7390 7391A supplemental static analysis tool 7392may be used to obtain a comprehensive list of all 7393possible points at which uninitialized data may be read. 7394 7395 7396@itemize * 7397 7398@item 7399@emph{Where run-time support routines are implicitly invoked} 7400 7401In the output from @emph{-gnatGL}, 7402run-time calls are explicitly listed as calls to the relevant 7403run-time routine. 7404 7405@item 7406@emph{Object code listing} 7407 7408This may be obtained either by using the @emph{-S} switch, 7409or the objdump utility. 7410 7411@item 7412@emph{Constructs known to be erroneous at compile time} 7413 7414These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 7415 7416@item 7417@emph{Stack usage information} 7418 7419Static stack usage data (maximum per-subprogram) can be obtained via the 7420@emph{-fstack-usage} switch to the compiler. 7421Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 7422to gnatbind 7423@end itemize 7424 7425 7426 7427@itemize * 7428 7429@item 7430@emph{Object code listing of entire partition} 7431 7432This can be obtained by compiling the partition with @emph{-S}, 7433or by applying objdump 7434to all the object files that are part of the partition. 7435 7436@item 7437@emph{A description of the run-time model} 7438 7439The full sources of the run-time are available, and the documentation of 7440these routines describes how these run-time routines interface to the 7441underlying operating system facilities. 7442 7443@item 7444@emph{Control and data-flow information} 7445@end itemize 7446 7447 7448A supplemental static analysis tool 7449may be used to obtain complete control and data-flow information, as well as 7450comprehensive messages identifying possible problems based on this 7451information. 7452 7453@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas 7454@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{e0}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{e1} 7455@section Pragma Secondary_Stack_Size 7456 7457 7458Syntax: 7459 7460@example 7461pragma Secondary_Stack_Size (integer_EXPRESSION); 7462@end example 7463 7464This pragma appears within the task definition of a single task declaration 7465or a task type declaration (like pragma @code{Storage_Size}) and applies to all 7466task objects of that type. The argument specifies the size of the secondary 7467stack to be used by these task objects, and must be of an integer type. The 7468secondary stack is used to handle functions that return a variable-sized 7469result, for example a function returning an unconstrained String. 7470 7471Note this pragma only applies to targets using fixed secondary stacks, like 7472VxWorks 653 and bare board targets, where a fixed block for the 7473secondary stack is allocated from the primary stack of the task. By default, 7474these targets assign a percentage of the primary stack for the secondary stack, 7475as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, 7476an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. 7477 7478For most targets, the pragma does not apply as the secondary stack grows on 7479demand: allocated as a chain of blocks in the heap. The default size of these 7480blocks can be modified via the @code{-D} binder option as described in 7481@cite{GNAT User's Guide}. 7482 7483Note that no check is made to see if the secondary stack can fit inside the 7484primary stack. 7485 7486Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} 7487is in effect. 7488 7489@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas 7490@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e2} 7491@section Pragma Share_Generic 7492 7493 7494Syntax: 7495 7496@example 7497pragma Share_Generic (GNAME @{, GNAME@}); 7498 7499GNAME ::= generic_unit_NAME | generic_instance_NAME 7500@end example 7501 7502This pragma is provided for compatibility with Dec Ada 83. It has 7503no effect in GNAT (which does not implement shared generics), other 7504than to check that the given names are all names of generic units or 7505generic instances. 7506 7507@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 7508@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e4} 7509@section Pragma Shared 7510 7511 7512This pragma is provided for compatibility with Ada 83. The syntax and 7513semantics are identical to pragma Atomic. 7514 7515@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 7516@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e5} 7517@section Pragma Short_Circuit_And_Or 7518 7519 7520Syntax: 7521 7522@example 7523pragma Short_Circuit_And_Or; 7524@end example 7525 7526This configuration pragma causes any occurrence of the AND operator applied to 7527operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 7528is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 7529may be useful in the context of certification protocols requiring the use of 7530short-circuited logical operators. If this configuration pragma occurs locally 7531within the file being compiled, it applies only to the file being compiled. 7532There is no requirement that all units in a partition use this option. 7533 7534@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 7535@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e6} 7536@section Pragma Short_Descriptors 7537 7538 7539Syntax: 7540 7541@example 7542pragma Short_Descriptors 7543@end example 7544 7545This pragma is provided for compatibility with other Ada implementations. It 7546is recognized but ignored by all current versions of GNAT. 7547 7548@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 7549@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e7}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e8} 7550@section Pragma Simple_Storage_Pool_Type 7551 7552 7553@geindex Storage pool 7554@geindex simple 7555 7556@geindex Simple storage pool 7557 7558Syntax: 7559 7560@example 7561pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 7562@end example 7563 7564A type can be established as a 'simple storage pool type' by applying 7565the representation pragma @code{Simple_Storage_Pool_Type} to the type. 7566A type named in the pragma must be a library-level immutably limited record 7567type or limited tagged type declared immediately within a package declaration. 7568The type can also be a limited private type whose full type is allowed as 7569a simple storage pool type. 7570 7571For a simple storage pool type @code{SSP}, nonabstract primitive subprograms 7572@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 7573are subtype conformant with the following subprogram declarations: 7574 7575@example 7576procedure Allocate 7577 (Pool : in out SSP; 7578 Storage_Address : out System.Address; 7579 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7580 Alignment : System.Storage_Elements.Storage_Count); 7581 7582procedure Deallocate 7583 (Pool : in out SSP; 7584 Storage_Address : System.Address; 7585 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7586 Alignment : System.Storage_Elements.Storage_Count); 7587 7588function Storage_Size (Pool : SSP) 7589 return System.Storage_Elements.Storage_Count; 7590@end example 7591 7592Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 7593@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 7594applying an unchecked deallocation has no effect other than to set its actual 7595parameter to null. If @code{Storage_Size} is not declared, then the 7596@code{Storage_Size} attribute applied to an access type associated with 7597a pool object of type SSP returns zero. Additional operations can be declared 7598for a simple storage pool type (such as for supporting a mark/release 7599storage-management discipline). 7600 7601An object of a simple storage pool type can be associated with an access 7602type by specifying the attribute 7603@ref{e9,,Simple_Storage_Pool}. For example: 7604 7605@example 7606My_Pool : My_Simple_Storage_Pool_Type; 7607 7608type Acc is access My_Data_Type; 7609 7610for Acc'Simple_Storage_Pool use My_Pool; 7611@end example 7612 7613See attribute @ref{e9,,Simple_Storage_Pool} 7614for further details. 7615 7616@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7617@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{eb} 7618@section Pragma Source_File_Name 7619 7620 7621Syntax: 7622 7623@example 7624pragma Source_File_Name ( 7625 [Unit_Name =>] unit_NAME, 7626 Spec_File_Name => STRING_LITERAL, 7627 [Index => INTEGER_LITERAL]); 7628 7629pragma Source_File_Name ( 7630 [Unit_Name =>] unit_NAME, 7631 Body_File_Name => STRING_LITERAL, 7632 [Index => INTEGER_LITERAL]); 7633@end example 7634 7635Use this to override the normal naming convention. It is a configuration 7636pragma, and so has the usual applicability of configuration pragmas 7637(i.e., it applies to either an entire partition, or to all units in a 7638compilation, or to a single unit, depending on how it is used. 7639@code{unit_name} is mapped to @code{file_name_literal}. The identifier for 7640the second argument is required, and indicates whether this is the file 7641name for the spec or for the body. 7642 7643The optional Index argument should be used when a file contains multiple 7644units, and when you do not want to use @code{gnatchop} to separate then 7645into multiple files (which is the recommended procedure to limit the 7646number of recompilations that are needed when some sources change). 7647For instance, if the source file @code{source.ada} contains 7648 7649@example 7650package B is 7651... 7652end B; 7653 7654with B; 7655procedure A is 7656begin 7657 .. 7658end A; 7659@end example 7660 7661you could use the following configuration pragmas: 7662 7663@example 7664pragma Source_File_Name 7665 (B, Spec_File_Name => "source.ada", Index => 1); 7666pragma Source_File_Name 7667 (A, Body_File_Name => "source.ada", Index => 2); 7668@end example 7669 7670Note that the @code{gnatname} utility can also be used to generate those 7671configuration pragmas. 7672 7673Another form of the @code{Source_File_Name} pragma allows 7674the specification of patterns defining alternative file naming schemes 7675to apply to all files. 7676 7677@example 7678pragma Source_File_Name 7679 ( [Spec_File_Name =>] STRING_LITERAL 7680 [,[Casing =>] CASING_SPEC] 7681 [,[Dot_Replacement =>] STRING_LITERAL]); 7682 7683pragma Source_File_Name 7684 ( [Body_File_Name =>] STRING_LITERAL 7685 [,[Casing =>] CASING_SPEC] 7686 [,[Dot_Replacement =>] STRING_LITERAL]); 7687 7688pragma Source_File_Name 7689 ( [Subunit_File_Name =>] STRING_LITERAL 7690 [,[Casing =>] CASING_SPEC] 7691 [,[Dot_Replacement =>] STRING_LITERAL]); 7692 7693CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7694@end example 7695 7696The first argument is a pattern that contains a single asterisk indicating 7697the point at which the unit name is to be inserted in the pattern string 7698to form the file name. The second argument is optional. If present it 7699specifies the casing of the unit name in the resulting file name string. 7700The default is lower case. Finally the third argument allows for systematic 7701replacement of any dots in the unit name by the specified string literal. 7702 7703Note that Source_File_Name pragmas should not be used if you are using 7704project files. The reason for this rule is that the project manager is not 7705aware of these pragmas, and so other tools that use the projet file would not 7706be aware of the intended naming conventions. If you are using project files, 7707file naming is controlled by Source_File_Name_Project pragmas, which are 7708usually supplied automatically by the project manager. A pragma 7709Source_File_Name cannot appear after a @ref{ec,,Pragma Source_File_Name_Project}. 7710 7711For more details on the use of the @code{Source_File_Name} pragma, see the 7712sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} 7713in the @cite{GNAT User's Guide}. 7714 7715@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7716@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ec}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{ed} 7717@section Pragma Source_File_Name_Project 7718 7719 7720This pragma has the same syntax and semantics as pragma Source_File_Name. 7721It is only allowed as a stand-alone configuration pragma. 7722It cannot appear after a @ref{ea,,Pragma Source_File_Name}, and 7723most importantly, once pragma Source_File_Name_Project appears, 7724no further Source_File_Name pragmas are allowed. 7725 7726The intention is that Source_File_Name_Project pragmas are always 7727generated by the Project Manager in a manner consistent with the naming 7728specified in a project file, and when naming is controlled in this manner, 7729it is not permissible to attempt to modify this naming scheme using 7730Source_File_Name or Source_File_Name_Project pragmas (which would not be 7731known to the project manager). 7732 7733@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7734@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ee} 7735@section Pragma Source_Reference 7736 7737 7738Syntax: 7739 7740@example 7741pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7742@end example 7743 7744This pragma must appear as the first line of a source file. 7745@code{integer_literal} is the logical line number of the line following 7746the pragma line (for use in error messages and debugging 7747information). @code{string_literal} is a static string constant that 7748specifies the file name to be used in error messages and debugging 7749information. This is most notably used for the output of @code{gnatchop} 7750with the @emph{-r} switch, to make sure that the original unchopped 7751source file is the one referred to. 7752 7753The second argument must be a string literal, it cannot be a static 7754string expression other than a string literal. This is because its value 7755is needed for error messages issued by all phases of the compiler. 7756 7757@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7758@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ef}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f0} 7759@section Pragma SPARK_Mode 7760 7761 7762Syntax: 7763 7764@example 7765pragma SPARK_Mode [(On | Off)] ; 7766@end example 7767 7768In general a program can have some parts that are in SPARK 2014 (and 7769follow all the rules in the SPARK Reference Manual), and some parts 7770that are full Ada 2012. 7771 7772The SPARK_Mode pragma is used to identify which parts are in SPARK 77732014 (by default programs are in full Ada). The SPARK_Mode pragma can 7774be used in the following places: 7775 7776 7777@itemize * 7778 7779@item 7780As a configuration pragma, in which case it sets the default mode for 7781all units compiled with this pragma. 7782 7783@item 7784Immediately following a library-level subprogram spec 7785 7786@item 7787Immediately within a library-level package body 7788 7789@item 7790Immediately following the @code{private} keyword of a library-level 7791package spec 7792 7793@item 7794Immediately following the @code{begin} keyword of a library-level 7795package body 7796 7797@item 7798Immediately within a library-level subprogram body 7799@end itemize 7800 7801Normally a subprogram or package spec/body inherits the current mode 7802that is active at the point it is declared. But this can be overridden 7803by pragma within the spec or body as above. 7804 7805The basic consistency rule is that you can't turn SPARK_Mode back 7806@code{On}, once you have explicitly (with a pragma) turned if 7807@code{Off}. So the following rules apply: 7808 7809If a subprogram spec has SPARK_Mode @code{Off}, then the body must 7810also have SPARK_Mode @code{Off}. 7811 7812For a package, we have four parts: 7813 7814 7815@itemize * 7816 7817@item 7818the package public declarations 7819 7820@item 7821the package private part 7822 7823@item 7824the body of the package 7825 7826@item 7827the elaboration code after @code{begin} 7828@end itemize 7829 7830For a package, the rule is that if you explicitly turn SPARK_Mode 7831@code{Off} for any part, then all the following parts must have 7832SPARK_Mode @code{Off}. Note that this may require repeating a pragma 7833SPARK_Mode (@code{Off}) in the body. For example, if we have a 7834configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 7835default everywhere, and one particular package spec has pragma 7836SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 7837the package body. 7838 7839@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7840@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{f1} 7841@section Pragma Static_Elaboration_Desired 7842 7843 7844Syntax: 7845 7846@example 7847pragma Static_Elaboration_Desired; 7848@end example 7849 7850This pragma is used to indicate that the compiler should attempt to initialize 7851statically the objects declared in the library unit to which the pragma applies, 7852when these objects are initialized (explicitly or implicitly) by an aggregate. 7853In the absence of this pragma, aggregates in object declarations are expanded 7854into assignments and loops, even when the aggregate components are static 7855constants. When the aggregate is present the compiler builds a static expression 7856that requires no run-time code, so that the initialized object can be placed in 7857read-only data space. If the components are not static, or the aggregate has 7858more that 100 components, the compiler emits a warning that the pragma cannot 7859be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7860construction of larger aggregates with static components that include an others 7861choice.) 7862 7863@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7864@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f2} 7865@section Pragma Stream_Convert 7866 7867 7868Syntax: 7869 7870@example 7871pragma Stream_Convert ( 7872 [Entity =>] type_LOCAL_NAME, 7873 [Read =>] function_NAME, 7874 [Write =>] function_NAME); 7875@end example 7876 7877This pragma provides an efficient way of providing user-defined stream 7878attributes. Not only is it simpler to use than specifying the attributes 7879directly, but more importantly, it allows the specification to be made in such 7880a way that the predefined unit Ada.Streams is not loaded unless it is actually 7881needed (i.e. unless the stream attributes are actually used); the use of 7882the Stream_Convert pragma adds no overhead at all, unless the stream 7883attributes are actually used on the designated type. 7884 7885The first argument specifies the type for which stream functions are 7886provided. The second parameter provides a function used to read values 7887of this type. It must name a function whose argument type may be any 7888subtype, and whose returned type must be the type given as the first 7889argument to the pragma. 7890 7891The meaning of the @code{Read} parameter is that if a stream attribute directly 7892or indirectly specifies reading of the type given as the first parameter, 7893then a value of the type given as the argument to the Read function is 7894read from the stream, and then the Read function is used to convert this 7895to the required target type. 7896 7897Similarly the @code{Write} parameter specifies how to treat write attributes 7898that directly or indirectly apply to the type given as the first parameter. 7899It must have an input parameter of the type specified by the first parameter, 7900and the return type must be the same as the input type of the Read function. 7901The effect is to first call the Write function to convert to the given stream 7902type, and then write the result type to the stream. 7903 7904The Read and Write functions must not be overloaded subprograms. If necessary 7905renamings can be supplied to meet this requirement. 7906The usage of this attribute is best illustrated by a simple example, taken 7907from the GNAT implementation of package Ada.Strings.Unbounded: 7908 7909@example 7910function To_Unbounded (S : String) return Unbounded_String 7911 renames To_Unbounded_String; 7912 7913pragma Stream_Convert 7914 (Unbounded_String, To_Unbounded, To_String); 7915@end example 7916 7917The specifications of the referenced functions, as given in the Ada 7918Reference Manual are: 7919 7920@example 7921function To_Unbounded_String (Source : String) 7922 return Unbounded_String; 7923 7924function To_String (Source : Unbounded_String) 7925 return String; 7926@end example 7927 7928The effect is that if the value of an unbounded string is written to a stream, 7929then the representation of the item in the stream is in the same format that 7930would be used for @code{Standard.String'Output}, and this same representation 7931is expected when a value of this type is read from the stream. Note that the 7932value written always includes the bounds, even for Unbounded_String'Write, 7933since Unbounded_String is not an array type. 7934 7935Note that the @code{Stream_Convert} pragma is not effective in the case of 7936a derived type of a non-limited tagged type. If such a type is specified then 7937the pragma is silently ignored, and the default implementation of the stream 7938attributes is used instead. 7939 7940@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7941@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f3} 7942@section Pragma Style_Checks 7943 7944 7945Syntax: 7946 7947@example 7948pragma Style_Checks (string_LITERAL | ALL_CHECKS | 7949 On | Off [, LOCAL_NAME]); 7950@end example 7951 7952This pragma is used in conjunction with compiler switches to control the 7953built in style checking provided by GNAT. The compiler switches, if set, 7954provide an initial setting for the switches, and this pragma may be used 7955to modify these settings, or the settings may be provided entirely by 7956the use of the pragma. This pragma can be used anywhere that a pragma 7957is legal, including use as a configuration pragma (including use in 7958the @code{gnat.adc} file). 7959 7960The form with a string literal specifies which style options are to be 7961activated. These are additive, so they apply in addition to any previously 7962set style check options. The codes for the options are the same as those 7963used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 7964For example the following two methods can be used to enable 7965layout checking: 7966 7967 7968@itemize * 7969 7970@item 7971@example 7972pragma Style_Checks ("l"); 7973@end example 7974 7975@item 7976@example 7977gcc -c -gnatyl ... 7978@end example 7979@end itemize 7980 7981The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent 7982to the use of the @code{gnaty} switch with no options. 7983See the @cite{GNAT User's Guide} for details.) 7984 7985Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). 7986In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check 7987options (i.e. equivalent to @code{-gnatyg}). 7988 7989The forms with @code{Off} and @code{On} 7990can be used to temporarily disable style checks 7991as shown in the following example: 7992 7993@example 7994pragma Style_Checks ("k"); -- requires keywords in lower case 7995pragma Style_Checks (Off); -- turn off style checks 7996NULL; -- this will not generate an error message 7997pragma Style_Checks (On); -- turn style checks back on 7998NULL; -- this will generate an error message 7999@end example 8000 8001Finally the two argument form is allowed only if the first argument is 8002@code{On} or @code{Off}. The effect is to turn of semantic style checks 8003for the specified entity, as shown in the following example: 8004 8005@example 8006pragma Style_Checks ("r"); -- require consistency of identifier casing 8007Arg : Integer; 8008Rf1 : Integer := ARG; -- incorrect, wrong case 8009pragma Style_Checks (Off, Arg); 8010Rf2 : Integer := ARG; -- OK, no error 8011@end example 8012 8013@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 8014@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f4} 8015@section Pragma Subtitle 8016 8017 8018Syntax: 8019 8020@example 8021pragma Subtitle ([Subtitle =>] STRING_LITERAL); 8022@end example 8023 8024This pragma is recognized for compatibility with other Ada compilers 8025but is ignored by GNAT. 8026 8027@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 8028@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f5} 8029@section Pragma Suppress 8030 8031 8032Syntax: 8033 8034@example 8035pragma Suppress (Identifier [, [On =>] Name]); 8036@end example 8037 8038This is a standard pragma, and supports all the check names required in 8039the RM. It is included here because GNAT recognizes some additional check 8040names that are implementation defined (as permitted by the RM): 8041 8042 8043@itemize * 8044 8045@item 8046@code{Alignment_Check} can be used to suppress alignment checks 8047on addresses used in address clauses. Such checks can also be suppressed 8048by suppressing range checks, but the specific use of @code{Alignment_Check} 8049allows suppression of alignment checks without suppressing other range checks. 8050Note that @code{Alignment_Check} is suppressed by default on machines (such as 8051the x86) with non-strict alignment. 8052 8053@item 8054@code{Atomic_Synchronization} can be used to suppress the special memory 8055synchronization instructions that are normally generated for access to 8056@code{Atomic} variables to ensure correct synchronization between tasks 8057that use such variables for synchronization purposes. 8058 8059@item 8060@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated 8061for a duplicated tag value when a tagged type is declared. 8062 8063@item 8064@code{Container_Checks} Can be used to suppress all checks within Ada.Containers 8065and instances of its children, including Tampering_Check. 8066 8067@item 8068@code{Tampering_Check} Can be used to suppress tampering check in the containers. 8069 8070@item 8071@code{Predicate_Check} can be used to control whether predicate checks are 8072active. It is applicable only to predicates for which the policy is 8073@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 8074predicate is ignored or checked for the whole program, the use of 8075@code{Suppress} and @code{Unsuppress} with this check name allows a given 8076predicate to be turned on and off at specific points in the program. 8077 8078@item 8079@code{Validity_Check} can be used specifically to control validity checks. 8080If @code{Suppress} is used to suppress validity checks, then no validity 8081checks are performed, including those specified by the appropriate compiler 8082switch or the @code{Validity_Checks} pragma. 8083 8084@item 8085Additional check names previously introduced by use of the @code{Check_Name} 8086pragma are also allowed. 8087@end itemize 8088 8089Note that pragma Suppress gives the compiler permission to omit 8090checks, but does not require the compiler to omit checks. The compiler 8091will generate checks if they are essentially free, even when they are 8092suppressed. In particular, if the compiler can prove that a certain 8093check will necessarily fail, it will generate code to do an 8094unconditional 'raise', even if checks are suppressed. The compiler 8095warns in this case. 8096 8097Of course, run-time checks are omitted whenever the compiler can prove 8098that they will not fail, whether or not checks are suppressed. 8099 8100@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 8101@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f6} 8102@section Pragma Suppress_All 8103 8104 8105Syntax: 8106 8107@example 8108pragma Suppress_All; 8109@end example 8110 8111This pragma can appear anywhere within a unit. 8112The effect is to apply @code{Suppress (All_Checks)} to the unit 8113in which it appears. This pragma is implemented for compatibility with DEC 8114Ada 83 usage where it appears at the end of a unit, and for compatibility 8115with Rational Ada, where it appears as a program unit pragma. 8116The use of the standard Ada pragma @code{Suppress (All_Checks)} 8117as a normal configuration pragma is the preferred usage in GNAT. 8118 8119@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 8120@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f7}@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f8} 8121@section Pragma Suppress_Debug_Info 8122 8123 8124Syntax: 8125 8126@example 8127pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 8128@end example 8129 8130This pragma can be used to suppress generation of debug information 8131for the specified entity. It is intended primarily for use in debugging 8132the debugger, and navigating around debugger problems. 8133 8134@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 8135@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f9} 8136@section Pragma Suppress_Exception_Locations 8137 8138 8139Syntax: 8140 8141@example 8142pragma Suppress_Exception_Locations; 8143@end example 8144 8145In normal mode, a raise statement for an exception by default generates 8146an exception message giving the file name and line number for the location 8147of the raise. This is useful for debugging and logging purposes, but this 8148entails extra space for the strings for the messages. The configuration 8149pragma @code{Suppress_Exception_Locations} can be used to suppress the 8150generation of these strings, with the result that space is saved, but the 8151exception message for such raises is null. This configuration pragma may 8152appear in a global configuration pragma file, or in a specific unit as 8153usual. It is not required that this pragma be used consistently within 8154a partition, so it is fine to have some units within a partition compiled 8155with this pragma and others compiled in normal mode without it. 8156 8157@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 8158@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{fb} 8159@section Pragma Suppress_Initialization 8160 8161 8162@geindex Suppressing initialization 8163 8164@geindex Initialization 8165@geindex suppression of 8166 8167Syntax: 8168 8169@example 8170pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 8171@end example 8172 8173Here variable_or_subtype_Name is the name introduced by a type declaration 8174or subtype declaration or the name of a variable introduced by an 8175object declaration. 8176 8177In the case of a type or subtype 8178this pragma suppresses any implicit or explicit initialization 8179for all variables of the given type or subtype, 8180including initialization resulting from the use of pragmas 8181Normalize_Scalars or Initialize_Scalars. 8182 8183This is considered a representation item, so it cannot be given after 8184the type is frozen. It applies to all subsequent object declarations, 8185and also any allocator that creates objects of the type. 8186 8187If the pragma is given for the first subtype, then it is considered 8188to apply to the base type and all its subtypes. If the pragma is given 8189for other than a first subtype, then it applies only to the given subtype. 8190The pragma may not be given after the type is frozen. 8191 8192Note that this includes eliminating initialization of discriminants 8193for discriminated types, and tags for tagged types. In these cases, 8194you will have to use some non-portable mechanism (e.g. address 8195overlays or unchecked conversion) to achieve required initialization 8196of these fields before accessing any object of the corresponding type. 8197 8198For the variable case, implicit initialization for the named variable 8199is suppressed, just as though its subtype had been given in a pragma 8200Suppress_Initialization, as described above. 8201 8202@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 8203@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fc} 8204@section Pragma Task_Name 8205 8206 8207Syntax 8208 8209@example 8210pragma Task_Name (string_EXPRESSION); 8211@end example 8212 8213This pragma appears within a task definition (like pragma 8214@code{Priority}) and applies to the task in which it appears. The 8215argument must be of type String, and provides a name to be used for 8216the task instance when the task is created. Note that this expression 8217is not required to be static, and in particular, it can contain 8218references to task discriminants. This facility can be used to 8219provide different names for different tasks as they are created, 8220as illustrated in the example below. 8221 8222The task name is recorded internally in the run-time structures 8223and is accessible to tools like the debugger. In addition the 8224routine @code{Ada.Task_Identification.Image} will return this 8225string, with a unique task address appended. 8226 8227@example 8228-- Example of the use of pragma Task_Name 8229 8230with Ada.Task_Identification; 8231use Ada.Task_Identification; 8232with Text_IO; use Text_IO; 8233procedure t3 is 8234 8235 type Astring is access String; 8236 8237 task type Task_Typ (Name : access String) is 8238 pragma Task_Name (Name.all); 8239 end Task_Typ; 8240 8241 task body Task_Typ is 8242 Nam : constant String := Image (Current_Task); 8243 begin 8244 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 8245 end Task_Typ; 8246 8247 type Ptr_Task is access Task_Typ; 8248 Task_Var : Ptr_Task; 8249 8250begin 8251 Task_Var := 8252 new Task_Typ (new String'("This is task 1")); 8253 Task_Var := 8254 new Task_Typ (new String'("This is task 2")); 8255end; 8256@end example 8257 8258@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 8259@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fd} 8260@section Pragma Task_Storage 8261 8262 8263Syntax: 8264 8265@example 8266pragma Task_Storage ( 8267 [Task_Type =>] LOCAL_NAME, 8268 [Top_Guard =>] static_integer_EXPRESSION); 8269@end example 8270 8271This pragma specifies the length of the guard area for tasks. The guard 8272area is an additional storage area allocated to a task. A value of zero 8273means that either no guard area is created or a minimal guard area is 8274created, depending on the target. This pragma can appear anywhere a 8275@code{Storage_Size} attribute definition clause is allowed for a task 8276type. 8277 8278@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 8279@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fe}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{ff} 8280@section Pragma Test_Case 8281 8282 8283@geindex Test cases 8284 8285Syntax: 8286 8287@example 8288pragma Test_Case ( 8289 [Name =>] static_string_Expression 8290 ,[Mode =>] (Nominal | Robustness) 8291 [, Requires => Boolean_Expression] 8292 [, Ensures => Boolean_Expression]); 8293@end example 8294 8295The @code{Test_Case} pragma allows defining fine-grain specifications 8296for use by testing tools. 8297The compiler checks the validity of the @code{Test_Case} pragma, but its 8298presence does not lead to any modification of the code generated by the 8299compiler. 8300 8301@code{Test_Case} pragmas may only appear immediately following the 8302(separate) declaration of a subprogram in a package declaration, inside 8303a package spec unit. Only other pragmas may intervene (that is appear 8304between the subprogram declaration and a test case). 8305 8306The compiler checks that boolean expressions given in @code{Requires} and 8307@code{Ensures} are valid, where the rules for @code{Requires} are the 8308same as the rule for an expression in @code{Precondition} and the rules 8309for @code{Ensures} are the same as the rule for an expression in 8310@code{Postcondition}. In particular, attributes @code{'Old} and 8311@code{'Result} can only be used within the @code{Ensures} 8312expression. The following is an example of use within a package spec: 8313 8314@example 8315package Math_Functions is 8316 ... 8317 function Sqrt (Arg : Float) return Float; 8318 pragma Test_Case (Name => "Test 1", 8319 Mode => Nominal, 8320 Requires => Arg < 10000, 8321 Ensures => Sqrt'Result < 10); 8322 ... 8323end Math_Functions; 8324@end example 8325 8326The meaning of a test case is that there is at least one context where 8327@code{Requires} holds such that, if the associated subprogram is executed in 8328that context, then @code{Ensures} holds when the subprogram returns. 8329Mode @code{Nominal} indicates that the input context should also satisfy the 8330precondition of the subprogram, and the output context should also satisfy its 8331postcondition. Mode @code{Robustness} indicates that the precondition and 8332postcondition of the subprogram should be ignored for this test case. 8333 8334@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 8335@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{101} 8336@section Pragma Thread_Local_Storage 8337 8338 8339@geindex Task specific storage 8340 8341@geindex TLS (Thread Local Storage) 8342 8343@geindex Task_Attributes 8344 8345Syntax: 8346 8347@example 8348pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 8349@end example 8350 8351This pragma specifies that the specified entity, which must be 8352a variable declared in a library-level package, is to be marked as 8353"Thread Local Storage" (@code{TLS}). On systems supporting this (which 8354include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each 8355thread (and hence each Ada task) to see a distinct copy of the variable. 8356 8357The variable must not have default initialization, and if there is 8358an explicit initialization, it must be either @code{null} for an 8359access variable, a static expression for a scalar variable, or a fully 8360static aggregate for a composite type, that is to say, an aggregate all 8361of whose components are static, and which does not include packed or 8362discriminated components. 8363 8364This provides a low-level mechanism similar to that provided by 8365the @code{Ada.Task_Attributes} package, but much more efficient 8366and is also useful in writing interface code that will interact 8367with foreign threads. 8368 8369If this pragma is used on a system where @code{TLS} is not supported, 8370then an error message will be generated and the program will be rejected. 8371 8372@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 8373@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{102} 8374@section Pragma Time_Slice 8375 8376 8377Syntax: 8378 8379@example 8380pragma Time_Slice (static_duration_EXPRESSION); 8381@end example 8382 8383For implementations of GNAT on operating systems where it is possible 8384to supply a time slice value, this pragma may be used for this purpose. 8385It is ignored if it is used in a system that does not allow this control, 8386or if it appears in other than the main program unit. 8387 8388@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 8389@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{103} 8390@section Pragma Title 8391 8392 8393Syntax: 8394 8395@example 8396pragma Title (TITLING_OPTION [, TITLING OPTION]); 8397 8398TITLING_OPTION ::= 8399 [Title =>] STRING_LITERAL, 8400| [Subtitle =>] STRING_LITERAL 8401@end example 8402 8403Syntax checked but otherwise ignored by GNAT. This is a listing control 8404pragma used in DEC Ada 83 implementations to provide a title and/or 8405subtitle for the program listing. The program listing generated by GNAT 8406does not have titles or subtitles. 8407 8408Unlike other pragmas, the full flexibility of named notation is allowed 8409for this pragma, i.e., the parameters may be given in any order if named 8410notation is used, and named and positional notation can be mixed 8411following the normal rules for procedure calls in Ada. 8412 8413@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 8414@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{104} 8415@section Pragma Type_Invariant 8416 8417 8418Syntax: 8419 8420@example 8421pragma Type_Invariant 8422 ([Entity =>] type_LOCAL_NAME, 8423 [Check =>] EXPRESSION); 8424@end example 8425 8426The @code{Type_Invariant} pragma is intended to be an exact 8427replacement for the language-defined @code{Type_Invariant} 8428aspect, and shares its restrictions and semantics. It differs 8429from the language defined @code{Invariant} pragma in that it 8430does not permit a string parameter, and it is 8431controlled by the assertion identifier @code{Type_Invariant} 8432rather than @code{Invariant}. 8433 8434@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 8435@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{106} 8436@section Pragma Type_Invariant_Class 8437 8438 8439Syntax: 8440 8441@example 8442pragma Type_Invariant_Class 8443 ([Entity =>] type_LOCAL_NAME, 8444 [Check =>] EXPRESSION); 8445@end example 8446 8447The @code{Type_Invariant_Class} pragma is intended to be an exact 8448replacement for the language-defined @code{Type_Invariant'Class} 8449aspect, and shares its restrictions and semantics. 8450 8451Note: This pragma is called @code{Type_Invariant_Class} rather than 8452@code{Type_Invariant'Class} because the latter would not be strictly 8453conforming to the allowed syntax for pragmas. The motivation 8454for providing pragmas equivalent to the aspects is to allow a program 8455to be written using the pragmas, and then compiled if necessary 8456using an Ada compiler that does not recognize the pragmas or 8457aspects, but is prepared to ignore the pragmas. The assertion 8458policy that controls this pragma is @code{Type_Invariant'Class}, 8459not @code{Type_Invariant_Class}. 8460 8461@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 8462@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{107} 8463@section Pragma Unchecked_Union 8464 8465 8466@geindex Unions in C 8467 8468Syntax: 8469 8470@example 8471pragma Unchecked_Union (first_subtype_LOCAL_NAME); 8472@end example 8473 8474This pragma is used to specify a representation of a record type that is 8475equivalent to a C union. It was introduced as a GNAT implementation defined 8476pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 8477pragma, making it language defined, and GNAT fully implements this extended 8478version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 8479details, consult the Ada 2012 Reference Manual, section B.3.3. 8480 8481@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 8482@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{108} 8483@section Pragma Unevaluated_Use_Of_Old 8484 8485 8486@geindex Attribute Old 8487 8488@geindex Attribute Loop_Entry 8489 8490@geindex Unevaluated_Use_Of_Old 8491 8492Syntax: 8493 8494@example 8495pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 8496@end example 8497 8498This pragma controls the processing of attributes Old and Loop_Entry. 8499If either of these attributes is used in a potentially unevaluated 8500expression (e.g. the then or else parts of an if expression), then 8501normally this usage is considered illegal if the prefix of the attribute 8502is other than an entity name. The language requires this 8503behavior for Old, and GNAT copies the same rule for Loop_Entry. 8504 8505The reason for this rule is that otherwise, we can have a situation 8506where we save the Old value, and this results in an exception, even 8507though we might not evaluate the attribute. Consider this example: 8508 8509@example 8510package UnevalOld is 8511 K : Character; 8512 procedure U (A : String; C : Boolean) -- ERROR 8513 with Post => (if C then A(1)'Old = K else True); 8514end; 8515@end example 8516 8517If procedure U is called with a string with a lower bound of 2, and 8518C false, then an exception would be raised trying to evaluate A(1) 8519on entry even though the value would not be actually used. 8520 8521Although the rule guarantees against this possibility, it is sometimes 8522too restrictive. For example if we know that the string has a lower 8523bound of 1, then we will never raise an exception. 8524The pragma @code{Unevaluated_Use_Of_Old} can be 8525used to modify this behavior. If the argument is @code{Error} then an 8526error is given (this is the default RM behavior). If the argument is 8527@code{Warn} then the usage is allowed as legal but with a warning 8528that an exception might be raised. If the argument is @code{Allow} 8529then the usage is allowed as legal without generating a warning. 8530 8531This pragma may appear as a configuration pragma, or in a declarative 8532part or package specification. In the latter case it applies to 8533uses up to the end of the corresponding statement sequence or 8534sequence of package declarations. 8535 8536@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 8537@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{109} 8538@section Pragma Unimplemented_Unit 8539 8540 8541Syntax: 8542 8543@example 8544pragma Unimplemented_Unit; 8545@end example 8546 8547If this pragma occurs in a unit that is processed by the compiler, GNAT 8548aborts with the message @code{xxx not implemented}, where 8549@code{xxx} is the name of the current compilation unit. This pragma is 8550intended to allow the compiler to handle unimplemented library units in 8551a clean manner. 8552 8553The abort only happens if code is being generated. Thus you can use 8554specs of unimplemented packages in syntax or semantic checking mode. 8555 8556@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas 8557@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{10b} 8558@section Pragma Universal_Aliasing 8559 8560 8561Syntax: 8562 8563@example 8564pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 8565@end example 8566 8567@code{type_LOCAL_NAME} must refer to a type declaration in the current 8568declarative part. The effect is to inhibit strict type-based aliasing 8569optimization for the given type. In other words, the effect is as though 8570access types designating this type were subject to pragma No_Strict_Aliasing. 8571For a detailed description of the strict aliasing optimization, and the 8572situations in which it must be suppressed, see the section on 8573@code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}. 8574 8575@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas 8576@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{10d} 8577@section Pragma Universal_Data 8578 8579 8580Syntax: 8581 8582@example 8583pragma Universal_Data [(library_unit_Name)]; 8584@end example 8585 8586This pragma is supported only for the AAMP target and is ignored for 8587other targets. The pragma specifies that all library-level objects 8588(Counter 0 data) associated with the library unit are to be accessed 8589and updated using universal addressing (24-bit addresses for AAMP5) 8590rather than the default of 16-bit Data Environment (DENV) addressing. 8591Use of this pragma will generally result in less efficient code for 8592references to global data associated with the library unit, but 8593allows such data to be located anywhere in memory. This pragma is 8594a library unit pragma, but can also be used as a configuration pragma 8595(including use in the @code{gnat.adc} file). The functionality 8596of this pragma is also available by applying the -univ switch on the 8597compilations of units where universal addressing of the data is desired. 8598 8599@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas 8600@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10f} 8601@section Pragma Unmodified 8602 8603 8604@geindex Warnings 8605@geindex unmodified 8606 8607Syntax: 8608 8609@example 8610pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8611@end example 8612 8613This pragma signals that the assignable entities (variables, 8614@code{out} parameters, @code{in out} parameters) whose names are listed are 8615deliberately not assigned in the current source unit. This 8616suppresses warnings about the 8617entities being referenced but not assigned, and in addition a warning will be 8618generated if one of these entities is in fact assigned in the 8619same unit as the pragma (or in the corresponding body, or one 8620of its subunits). 8621 8622This is particularly useful for clearly signaling that a particular 8623parameter is not modified, even though the spec suggests that it might 8624be. 8625 8626For the variable case, warnings are never given for unreferenced variables 8627whose name contains one of the substrings 8628@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8629are typically to be used in cases where such warnings are expected. 8630Thus it is never necessary to use @code{pragma Unmodified} for such 8631variables, though it is harmless to do so. 8632 8633@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8634@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{111} 8635@section Pragma Unreferenced 8636 8637 8638@geindex Warnings 8639@geindex unreferenced 8640 8641Syntax: 8642 8643@example 8644pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8645pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8646@end example 8647 8648This pragma signals that the entities whose names are listed are 8649deliberately not referenced in the current source unit after the 8650occurrence of the pragma. This 8651suppresses warnings about the 8652entities being unreferenced, and in addition a warning will be 8653generated if one of these entities is in fact subsequently referenced in the 8654same unit as the pragma (or in the corresponding body, or one 8655of its subunits). 8656 8657This is particularly useful for clearly signaling that a particular 8658parameter is not referenced in some particular subprogram implementation 8659and that this is deliberate. It can also be useful in the case of 8660objects declared only for their initialization or finalization side 8661effects. 8662 8663If @code{LOCAL_NAME} identifies more than one matching homonym in the 8664current scope, then the entity most recently declared is the one to which 8665the pragma applies. Note that in the case of accept formals, the pragma 8666Unreferenced may appear immediately after the keyword @code{do} which 8667allows the indication of whether or not accept formals are referenced 8668or not to be given individually for each accept statement. 8669 8670The left hand side of an assignment does not count as a reference for the 8671purpose of this pragma. Thus it is fine to assign to an entity for which 8672pragma Unreferenced is given. 8673 8674Note that if a warning is desired for all calls to a given subprogram, 8675regardless of whether they occur in the same unit as the subprogram 8676declaration, then this pragma should not be used (calls from another 8677unit would not be flagged); pragma Obsolescent can be used instead 8678for this purpose, see @ref{af,,Pragma Obsolescent}. 8679 8680The second form of pragma @code{Unreferenced} is used within a context 8681clause. In this case the arguments must be unit names of units previously 8682mentioned in @code{with} clauses (similar to the usage of pragma 8683@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 8684units and unreferenced entities within these units. 8685 8686For the variable case, warnings are never given for unreferenced variables 8687whose name contains one of the substrings 8688@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8689are typically to be used in cases where such warnings are expected. 8690Thus it is never necessary to use @code{pragma Unreferenced} for such 8691variables, though it is harmless to do so. 8692 8693@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8694@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{112}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{113} 8695@section Pragma Unreferenced_Objects 8696 8697 8698@geindex Warnings 8699@geindex unreferenced 8700 8701Syntax: 8702 8703@example 8704pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8705@end example 8706 8707This pragma signals that for the types or subtypes whose names are 8708listed, objects which are declared with one of these types or subtypes may 8709not be referenced, and if no references appear, no warnings are given. 8710 8711This is particularly useful for objects which are declared solely for their 8712initialization and finalization effect. Such variables are sometimes referred 8713to as RAII variables (Resource Acquisition Is Initialization). Using this 8714pragma on the relevant type (most typically a limited controlled type), the 8715compiler will automatically suppress unwanted warnings about these variables 8716not being referenced. 8717 8718@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8719@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{114} 8720@section Pragma Unreserve_All_Interrupts 8721 8722 8723Syntax: 8724 8725@example 8726pragma Unreserve_All_Interrupts; 8727@end example 8728 8729Normally certain interrupts are reserved to the implementation. Any attempt 8730to attach an interrupt causes Program_Error to be raised, as described in 8731RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 8732many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8733reserved to the implementation, so that @code{Ctrl-C} can be used to 8734interrupt execution. 8735 8736If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 8737a program, then all such interrupts are unreserved. This allows the 8738program to handle these interrupts, but disables their standard 8739functions. For example, if this pragma is used, then pressing 8740@code{Ctrl-C} will not automatically interrupt execution. However, 8741a program can then handle the @code{SIGINT} interrupt as it chooses. 8742 8743For a full list of the interrupts handled in a specific implementation, 8744see the source code for the spec of @code{Ada.Interrupts.Names} in 8745file @code{a-intnam.ads}. This is a target dependent file that contains the 8746list of interrupts recognized for a given target. The documentation in 8747this file also specifies what interrupts are affected by the use of 8748the @code{Unreserve_All_Interrupts} pragma. 8749 8750For a more general facility for controlling what interrupts can be 8751handled, see pragma @code{Interrupt_State}, which subsumes the functionality 8752of the @code{Unreserve_All_Interrupts} pragma. 8753 8754@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8755@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{115} 8756@section Pragma Unsuppress 8757 8758 8759Syntax: 8760 8761@example 8762pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8763@end example 8764 8765This pragma undoes the effect of a previous pragma @code{Suppress}. If 8766there is no corresponding pragma @code{Suppress} in effect, it has no 8767effect. The range of the effect is the same as for pragma 8768@code{Suppress}. The meaning of the arguments is identical to that used 8769in pragma @code{Suppress}. 8770 8771One important application is to ensure that checks are on in cases where 8772code depends on the checks for its correct functioning, so that the code 8773will compile correctly even if the compiler switches are set to suppress 8774checks. For example, in a program that depends on external names of tagged 8775types and wants to ensure that the duplicated tag check occurs even if all 8776run-time checks are suppressed by a compiler switch, the following 8777configuration pragma will ensure this test is not suppressed: 8778 8779@example 8780pragma Unsuppress (Duplicated_Tag_Check); 8781@end example 8782 8783This pragma is standard in Ada 2005. It is available in all earlier versions 8784of Ada as an implementation-defined pragma. 8785 8786Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8787number of implementation-defined check names. See the description of pragma 8788@code{Suppress} for full details. 8789 8790@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas 8791@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{116} 8792@section Pragma Use_VADS_Size 8793 8794 8795@geindex Size 8796@geindex VADS compatibility 8797 8798@geindex Rational profile 8799 8800Syntax: 8801 8802@example 8803pragma Use_VADS_Size; 8804@end example 8805 8806This is a configuration pragma. In a unit to which it applies, any use 8807of the 'Size attribute is automatically interpreted as a use of the 8808'VADS_Size attribute. Note that this may result in incorrect semantic 8809processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8810the handling of existing code which depends on the interpretation of Size 8811as implemented in the VADS compiler. See description of the VADS_Size 8812attribute for further details. 8813 8814@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas 8815@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{118} 8816@section Pragma Unused 8817 8818 8819@geindex Warnings 8820@geindex unused 8821 8822Syntax: 8823 8824@example 8825pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); 8826@end example 8827 8828This pragma signals that the assignable entities (variables, 8829@code{out} parameters, and @code{in out} parameters) whose names are listed 8830deliberately do not get assigned or referenced in the current source unit 8831after the occurrence of the pragma in the current source unit. This 8832suppresses warnings about the entities that are unreferenced and/or not 8833assigned, and, in addition, a warning will be generated if one of these 8834entities gets assigned or subsequently referenced in the same unit as the 8835pragma (in the corresponding body or one of its subunits). 8836 8837This is particularly useful for clearly signaling that a particular 8838parameter is not modified or referenced, even though the spec suggests 8839that it might be. 8840 8841For the variable case, warnings are never given for unreferenced 8842variables whose name contains one of the substrings 8843@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8844are typically to be used in cases where such warnings are expected. 8845Thus it is never necessary to use @code{pragma Unmodified} for such 8846variables, though it is harmless to do so. 8847 8848@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas 8849@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{119} 8850@section Pragma Validity_Checks 8851 8852 8853Syntax: 8854 8855@example 8856pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8857@end example 8858 8859This pragma is used in conjunction with compiler switches to control the 8860built-in validity checking provided by GNAT. The compiler switches, if set 8861provide an initial setting for the switches, and this pragma may be used 8862to modify these settings, or the settings may be provided entirely by 8863the use of the pragma. This pragma can be used anywhere that a pragma 8864is legal, including use as a configuration pragma (including use in 8865the @code{gnat.adc} file). 8866 8867The form with a string literal specifies which validity options are to be 8868activated. The validity checks are first set to include only the default 8869reference manual settings, and then a string of letters in the string 8870specifies the exact set of options required. The form of this string 8871is exactly as described for the @emph{-gnatVx} compiler switch (see the 8872GNAT User's Guide for details). For example the following two 8873methods can be used to enable validity checking for mode @code{in} and 8874@code{in out} subprogram parameters: 8875 8876 8877@itemize * 8878 8879@item 8880@example 8881pragma Validity_Checks ("im"); 8882@end example 8883 8884@item 8885@example 8886$ gcc -c -gnatVim ... 8887@end example 8888@end itemize 8889 8890The form ALL_CHECKS activates all standard checks (its use is equivalent 8891to the use of the @code{gnatVa} switch). 8892 8893The forms with @code{Off} and @code{On} can be used to temporarily disable 8894validity checks as shown in the following example: 8895 8896@example 8897pragma Validity_Checks ("c"); -- validity checks for copies 8898pragma Validity_Checks (Off); -- turn off validity checks 8899A := B; -- B will not be validity checked 8900pragma Validity_Checks (On); -- turn validity checks back on 8901A := C; -- C will be validity checked 8902@end example 8903 8904@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8905@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{11a}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{11b} 8906@section Pragma Volatile 8907 8908 8909Syntax: 8910 8911@example 8912pragma Volatile (LOCAL_NAME); 8913@end example 8914 8915This pragma is defined by the Ada Reference Manual, and the GNAT 8916implementation is fully conformant with this definition. The reason it 8917is mentioned in this section is that a pragma of the same name was supplied 8918in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8919implementation of pragma Volatile is upwards compatible with the 8920implementation in DEC Ada 83. 8921 8922@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8923@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{11c}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{11d} 8924@section Pragma Volatile_Full_Access 8925 8926 8927Syntax: 8928 8929@example 8930pragma Volatile_Full_Access (LOCAL_NAME); 8931@end example 8932 8933This is similar in effect to pragma Volatile, except that any reference to the 8934object is guaranteed to be done only with instructions that read or write all 8935the bits of the object. Furthermore, if the object is of a composite type, 8936then any reference to a subcomponent of the object is guaranteed to read 8937and/or write all the bits of the object. 8938 8939The intention is that this be suitable for use with memory-mapped I/O devices 8940on some machines. Note that there are two important respects in which this is 8941different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} 8942object is not a sequential action in the RM 9.10 sense and, therefore, does 8943not create a synchronization point. Second, in the case of @code{pragma Atomic}, 8944there is no guarantee that all the bits will be accessed if the reference 8945is not to the whole object; the compiler is allowed (and generally will) 8946access only part of the object in this case. 8947 8948It is not permissible to specify @code{Atomic} and @code{Volatile_Full_Access} for 8949the same type or object. 8950 8951It is not permissible to specify @code{Volatile_Full_Access} for a composite 8952(record or array) type or object that has an @code{Aliased} subcomponent. 8953 8954@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8955@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11e}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11f} 8956@section Pragma Volatile_Function 8957 8958 8959Syntax: 8960 8961@example 8962pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8963@end example 8964 8965For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} 8966in the SPARK 2014 Reference Manual, section 7.1.2. 8967 8968@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8969@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{120} 8970@section Pragma Warning_As_Error 8971 8972 8973Syntax: 8974 8975@example 8976pragma Warning_As_Error (static_string_EXPRESSION); 8977@end example 8978 8979This configuration pragma allows the programmer to specify a set 8980of warnings that will be treated as errors. Any warning that 8981matches the pattern given by the pragma argument will be treated 8982as an error. This gives more precise control than -gnatwe, 8983which treats warnings as errors. 8984 8985This pragma can apply to regular warnings (messages enabled by -gnatw) 8986and to style warnings (messages that start with "(style)", 8987enabled by -gnaty). 8988 8989The pattern may contain asterisks, which match zero or more characters 8990in the message. For example, you can use @code{pragma Warning_As_Error 8991("bits of*unused")} to treat the warning message @code{warning: 960 bits of 8992"a" unused} as an error. All characters other than asterisk are treated 8993as literal characters in the match. The match is case insensitive; for 8994example XYZ matches xyz. 8995 8996Note that the pattern matches if it occurs anywhere within the warning 8997message string (it is not necessary to put an asterisk at the start and 8998the end of the message, since this is implied). 8999 9000Another possibility for the static_string_EXPRESSION which works whether 9001or not error tags are enabled (@emph{-gnatw.d}) is to use a single 9002@emph{-gnatw} tag string, enclosed in brackets, 9003as shown in the example below, to treat one category of warnings as errors. 9004Note that if you want to treat multiple categories of warnings as errors, 9005you can use multiple pragma Warning_As_Error. 9006 9007The above use of patterns to match the message applies only to warning 9008messages generated by the front end. This pragma can also be applied to 9009warnings provided by the back end and mentioned in @ref{121,,Pragma Warnings}. 9010By using a single full @emph{-Wxxx} switch in the pragma, such warnings 9011can also be treated as errors. 9012 9013The pragma can appear either in a global configuration pragma file 9014(e.g. @code{gnat.adc}), or at the start of a file. Given a global 9015configuration pragma file containing: 9016 9017@example 9018pragma Warning_As_Error ("[-gnatwj]"); 9019@end example 9020 9021which will treat all obsolescent feature warnings as errors, the 9022following program compiles as shown (compile options here are 9023@emph{-gnatwa.d -gnatl -gnatj55}). 9024 9025@example 9026 1. pragma Warning_As_Error ("*never assigned*"); 9027 2. function Warnerr return String is 9028 3. X : Integer; 9029 | 9030 >>> error: variable "X" is never read and 9031 never assigned [-gnatwv] [warning-as-error] 9032 9033 4. Y : Integer; 9034 | 9035 >>> warning: variable "Y" is assigned but 9036 never read [-gnatwu] 9037 9038 5. begin 9039 6. Y := 0; 9040 7. return %ABC%; 9041 | 9042 >>> error: use of "%" is an obsolescent 9043 feature (RM J.2(4)), use """ instead 9044 [-gnatwj] [warning-as-error] 9045 9046 8. end; 9047 90488 lines: No errors, 3 warnings (2 treated as errors) 9049@end example 9050 9051Note that this pragma does not affect the set of warnings issued in 9052any way, it merely changes the effect of a matching warning if one 9053is produced as a result of other warnings options. As shown in this 9054example, if the pragma results in a warning being treated as an error, 9055the tag is changed from "warning:" to "error:" and the string 9056"[warning-as-error]" is appended to the end of the message. 9057 9058@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 9059@anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{122}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{121} 9060@section Pragma Warnings 9061 9062 9063Syntax: 9064 9065@example 9066pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 9067 9068DETAILS ::= On | Off 9069DETAILS ::= On | Off, local_NAME 9070DETAILS ::= static_string_EXPRESSION 9071DETAILS ::= On | Off, static_string_EXPRESSION 9072 9073TOOL_NAME ::= GNAT | GNATProve 9074 9075REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 9076@end example 9077 9078Note: in Ada 83 mode, a string literal may be used in place of a static string 9079expression (which does not exist in Ada 83). 9080 9081Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the 9082second form is always understood. If the intention is to use 9083the fourth form, then you can write @code{NAME & ""} to force the 9084intepretation as a @emph{static_string_EXPRESSION}. 9085 9086Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted 9087that way. The use of the @code{TOOL_NAME} argument is relevant only to users 9088of SPARK and GNATprove, see last part of this section for details. 9089 9090Normally warnings are enabled, with the output being controlled by 9091the command line switch. Warnings (@code{Off}) turns off generation of 9092warnings until a Warnings (@code{On}) is encountered or the end of the 9093current unit. If generation of warnings is turned off using this 9094pragma, then some or all of the warning messages are suppressed, 9095regardless of the setting of the command line switches. 9096 9097The @code{Reason} parameter may optionally appear as the last argument 9098in any of the forms of this pragma. It is intended purely for the 9099purposes of documenting the reason for the @code{Warnings} pragma. 9100The compiler will check that the argument is a static string but 9101otherwise ignore this argument. Other tools may provide specialized 9102processing for this string. 9103 9104The form with a single argument (or two arguments if Reason present), 9105where the first argument is @code{ON} or @code{OFF} 9106may be used as a configuration pragma. 9107 9108If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for 9109the specified entity. This suppression is effective from the point where 9110it occurs till the end of the extended scope of the variable (similar to 9111the scope of @code{Suppress}). This form cannot be used as a configuration 9112pragma. 9113 9114In the case where the first argument is other than @code{ON} or 9115@code{OFF}, 9116the third form with a single static_string_EXPRESSION argument (and possible 9117reason) provides more precise 9118control over which warnings are active. The string is a list of letters 9119specifying which warnings are to be activated and which deactivated. The 9120code for these letters is the same as the string used in the command 9121line switch controlling warnings. For a brief summary, use the gnatmake 9122command with no arguments, which will generate usage information containing 9123the list of warnings switches supported. For 9124full details see the section on @code{Warning Message Control} in the 9125@cite{GNAT User's Guide}. 9126This form can also be used as a configuration pragma. 9127 9128The warnings controlled by the @code{-gnatw} switch are generated by the 9129front end of the compiler. The GCC back end can provide additional warnings 9130and they are controlled by the @code{-W} switch. Such warnings can be 9131identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the 9132message which designates the @code{-W@emph{xxx}} switch that controls the message. 9133The form with a single @emph{static_string_EXPRESSION} argument also works for these 9134warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this 9135case. The above reference lists a few examples of these additional warnings. 9136 9137The specified warnings will be in effect until the end of the program 9138or another pragma @code{Warnings} is encountered. The effect of the pragma is 9139cumulative. Initially the set of warnings is the standard default set 9140as possibly modified by compiler switches. Then each pragma Warning 9141modifies this set of warnings as specified. This form of the pragma may 9142also be used as a configuration pragma. 9143 9144The fourth form, with an @code{On|Off} parameter and a string, is used to 9145control individual messages, based on their text. The string argument 9146is a pattern that is used to match against the text of individual 9147warning messages (not including the initial "warning: " tag). 9148 9149The pattern may contain asterisks, which match zero or more characters in 9150the message. For example, you can use 9151@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning 9152message @code{warning: 960 bits of "a" unused}. No other regular 9153expression notations are permitted. All characters other than asterisk in 9154these three specific cases are treated as literal characters in the match. 9155The match is case insensitive, for example XYZ matches xyz. 9156 9157Note that the pattern matches if it occurs anywhere within the warning 9158message string (it is not necessary to put an asterisk at the start and 9159the end of the message, since this is implied). 9160 9161The above use of patterns to match the message applies only to warning 9162messages generated by the front end. This form of the pragma with a string 9163argument can also be used to control warnings provided by the back end and 9164mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, 9165such warnings can be turned on and off. 9166 9167There are two ways to use the pragma in this form. The OFF form can be used 9168as a configuration pragma. The effect is to suppress all warnings (if any) 9169that match the pattern string throughout the compilation (or match the 9170-W switch in the back end case). 9171 9172The second usage is to suppress a warning locally, and in this case, two 9173pragmas must appear in sequence: 9174 9175@example 9176pragma Warnings (Off, Pattern); 9177... code where given warning is to be suppressed 9178pragma Warnings (On, Pattern); 9179@end example 9180 9181In this usage, the pattern string must match in the Off and On 9182pragmas, and (if @emph{-gnatw.w} is given) at least one matching 9183warning must be suppressed. 9184 9185Note: if the ON form is not found, then the effect of the OFF form extends 9186until the end of the file (pragma Warnings is purely textual, so its effect 9187does not stop at the end of the enclosing scope). 9188 9189Note: to write a string that will match any warning, use the string 9190@code{"***"}. It will not work to use a single asterisk or two 9191asterisks since this looks like an operator name. This form with three 9192asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching 9193@code{pragma Warnings (On, "***")} will be required. This can be 9194helpful in avoiding forgetting to turn warnings back on. 9195 9196Note: the debug flag @code{-gnatd.i} can be 9197used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 9198be useful in checking whether obsolete pragmas in existing programs are hiding 9199real problems. 9200 9201Note: pragma Warnings does not affect the processing of style messages. See 9202separate entry for pragma Style_Checks for control of style messages. 9203 9204Users of the formal verification tool GNATprove for the SPARK subset of Ada may 9205use the version of the pragma with a @code{TOOL_NAME} parameter. 9206 9207If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the 9208compiler or @code{GNATprove} for the formal verification tool. A given tool only 9209takes into account pragma Warnings that do not specify a tool name, or that 9210specify the matching tool name. This makes it possible to disable warnings 9211selectively for each tool, and as a consequence to detect useless pragma 9212Warnings with switch @code{-gnatw.w}. 9213 9214@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 9215@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{123} 9216@section Pragma Weak_External 9217 9218 9219Syntax: 9220 9221@example 9222pragma Weak_External ([Entity =>] LOCAL_NAME); 9223@end example 9224 9225@code{LOCAL_NAME} must refer to an object that is declared at the library 9226level. This pragma specifies that the given entity should be marked as a 9227weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 9228in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead 9229of a regular symbol, that is to say a symbol that does not have to be 9230resolved by the linker if used in conjunction with a pragma Import. 9231 9232When a weak symbol is not resolved by the linker, its address is set to 9233zero. This is useful in writing interfaces to external modules that may 9234or may not be linked in the final executable, for example depending on 9235configuration settings. 9236 9237If a program references at run time an entity to which this pragma has been 9238applied, and the corresponding symbol was not resolved at link time, then 9239the execution of the program is erroneous. It is not erroneous to take the 9240Address of such an entity, for example to guard potential references, 9241as shown in the example below. 9242 9243Some file formats do not support weak symbols so not all target machines 9244support this pragma. 9245 9246@example 9247-- Example of the use of pragma Weak_External 9248 9249package External_Module is 9250 key : Integer; 9251 pragma Import (C, key); 9252 pragma Weak_External (key); 9253 function Present return boolean; 9254end External_Module; 9255 9256with System; use System; 9257package body External_Module is 9258 function Present return boolean is 9259 begin 9260 return key'Address /= System.Null_Address; 9261 end Present; 9262end External_Module; 9263@end example 9264 9265@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 9266@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{124} 9267@section Pragma Wide_Character_Encoding 9268 9269 9270Syntax: 9271 9272@example 9273pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 9274@end example 9275 9276This pragma specifies the wide character encoding to be used in program 9277source text appearing subsequently. It is a configuration pragma, but may 9278also be used at any point that a pragma is allowed, and it is permissible 9279to have more than one such pragma in a file, allowing multiple encodings 9280to appear within the same file. 9281 9282However, note that the pragma cannot immediately precede the relevant 9283wide character, because then the previous encoding will still be in 9284effect, causing "illegal character" errors. 9285 9286The argument can be an identifier or a character literal. In the identifier 9287case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 9288@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 9289case it is correspondingly one of the characters @code{h}, @code{u}, 9290@code{s}, @code{e}, @code{8}, or @code{b}. 9291 9292Note that when the pragma is used within a file, it affects only the 9293encoding within that file, and does not affect withed units, specs, 9294or subunits. 9295 9296@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 9297@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{125}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{126}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{127} 9298@chapter Implementation Defined Aspects 9299 9300 9301Ada defines (throughout the Ada 2012 reference manual, summarized 9302in Annex K) a set of aspects that can be specified for certain entities. 9303These language defined aspects are implemented in GNAT in Ada 2012 mode 9304and work as described in the Ada 2012 Reference Manual. 9305 9306In addition, Ada 2012 allows implementations to define additional aspects 9307whose meaning is defined by the implementation. GNAT provides 9308a number of these implementation-defined aspects which can be used 9309to extend and enhance the functionality of the compiler. This section of 9310the GNAT reference manual describes these additional aspects. 9311 9312Note that any program using these aspects may not be portable to 9313other compilers (although GNAT implements this set of aspects on all 9314platforms). Therefore if portability to other compilers is an important 9315consideration, you should minimize the use of these aspects. 9316 9317Note that for many of these aspects, the effect is essentially similar 9318to the use of a pragma or attribute specification with the same name 9319applied to the entity. For example, if we write: 9320 9321@example 9322type R is range 1 .. 100 9323 with Value_Size => 10; 9324@end example 9325 9326then the effect is the same as: 9327 9328@example 9329type R is range 1 .. 100; 9330for R'Value_Size use 10; 9331@end example 9332 9333and if we write: 9334 9335@example 9336type R is new Integer 9337 with Shared => True; 9338@end example 9339 9340then the effect is the same as: 9341 9342@example 9343type R is new Integer; 9344pragma Shared (R); 9345@end example 9346 9347In the documentation below, such cases are simply marked 9348as being boolean aspects equivalent to the corresponding pragma 9349or attribute definition clause. 9350 9351@menu 9352* Aspect Abstract_State:: 9353* Aspect Annotate:: 9354* Aspect Async_Readers:: 9355* Aspect Async_Writers:: 9356* Aspect Constant_After_Elaboration:: 9357* Aspect Contract_Cases:: 9358* Aspect Depends:: 9359* Aspect Default_Initial_Condition:: 9360* Aspect Dimension:: 9361* Aspect Dimension_System:: 9362* Aspect Disable_Controlled:: 9363* Aspect Effective_Reads:: 9364* Aspect Effective_Writes:: 9365* Aspect Extensions_Visible:: 9366* Aspect Favor_Top_Level:: 9367* Aspect Ghost:: 9368* Aspect Global:: 9369* Aspect Initial_Condition:: 9370* Aspect Initializes:: 9371* Aspect Inline_Always:: 9372* Aspect Invariant:: 9373* Aspect Invariant'Class:: 9374* Aspect Iterable:: 9375* Aspect Linker_Section:: 9376* Aspect Lock_Free:: 9377* Aspect Max_Queue_Length:: 9378* Aspect No_Caching:: 9379* Aspect No_Elaboration_Code_All:: 9380* Aspect No_Inline:: 9381* Aspect No_Tagged_Streams:: 9382* Aspect Object_Size:: 9383* Aspect Obsolescent:: 9384* Aspect Part_Of:: 9385* Aspect Persistent_BSS:: 9386* Aspect Predicate:: 9387* Aspect Pure_Function:: 9388* Aspect Refined_Depends:: 9389* Aspect Refined_Global:: 9390* Aspect Refined_Post:: 9391* Aspect Refined_State:: 9392* Aspect Remote_Access_Type:: 9393* Aspect Secondary_Stack_Size:: 9394* Aspect Scalar_Storage_Order:: 9395* Aspect Shared:: 9396* Aspect Simple_Storage_Pool:: 9397* Aspect Simple_Storage_Pool_Type:: 9398* Aspect SPARK_Mode:: 9399* Aspect Suppress_Debug_Info:: 9400* Aspect Suppress_Initialization:: 9401* Aspect Test_Case:: 9402* Aspect Thread_Local_Storage:: 9403* Aspect Universal_Aliasing:: 9404* Aspect Universal_Data:: 9405* Aspect Unmodified:: 9406* Aspect Unreferenced:: 9407* Aspect Unreferenced_Objects:: 9408* Aspect Value_Size:: 9409* Aspect Volatile_Full_Access:: 9410* Aspect Volatile_Function:: 9411* Aspect Warnings:: 9412 9413@end menu 9414 9415@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects 9416@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{128} 9417@section Aspect Abstract_State 9418 9419 9420@geindex Abstract_State 9421 9422This aspect is equivalent to @ref{1c,,pragma Abstract_State}. 9423 9424@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 9425@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{129} 9426@section Aspect Annotate 9427 9428 9429@geindex Annotate 9430 9431There are three forms of this aspect (where ID is an identifier, 9432and ARG is a general expression), 9433corresponding to @ref{2a,,pragma Annotate}. 9434 9435 9436@table @asis 9437 9438@item @emph{Annotate => ID} 9439 9440Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9441 9442@item @emph{Annotate => (ID)} 9443 9444Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9445 9446@item @emph{Annotate => (ID ,ID @{, ARG@})} 9447 9448Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} 9449@end table 9450 9451@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects 9452@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{12a} 9453@section Aspect Async_Readers 9454 9455 9456@geindex Async_Readers 9457 9458This boolean aspect is equivalent to @ref{31,,pragma Async_Readers}. 9459 9460@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 9461@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{12b} 9462@section Aspect Async_Writers 9463 9464 9465@geindex Async_Writers 9466 9467This boolean aspect is equivalent to @ref{34,,pragma Async_Writers}. 9468 9469@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 9470@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{12c} 9471@section Aspect Constant_After_Elaboration 9472 9473 9474@geindex Constant_After_Elaboration 9475 9476This aspect is equivalent to @ref{45,,pragma Constant_After_Elaboration}. 9477 9478@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 9479@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{12d} 9480@section Aspect Contract_Cases 9481 9482 9483@geindex Contract_Cases 9484 9485This aspect is equivalent to @ref{47,,pragma Contract_Cases}, the sequence 9486of clauses being enclosed in parentheses so that syntactically it is an 9487aggregate. 9488 9489@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 9490@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12e} 9491@section Aspect Depends 9492 9493 9494@geindex Depends 9495 9496This aspect is equivalent to @ref{56,,pragma Depends}. 9497 9498@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 9499@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12f} 9500@section Aspect Default_Initial_Condition 9501 9502 9503@geindex Default_Initial_Condition 9504 9505This aspect is equivalent to @ref{51,,pragma Default_Initial_Condition}. 9506 9507@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 9508@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{130} 9509@section Aspect Dimension 9510 9511 9512@geindex Dimension 9513 9514The @code{Dimension} aspect is used to specify the dimensions of a given 9515subtype of a dimensioned numeric type. The aspect also specifies a symbol 9516used when doing formatted output of dimensioned quantities. The syntax is: 9517 9518@example 9519with Dimension => 9520 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 9521 9522SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 9523 9524DIMENSION_VALUE ::= 9525 RATIONAL 9526| others => RATIONAL 9527| DISCRETE_CHOICE_LIST => RATIONAL 9528 9529RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 9530@end example 9531 9532This aspect can only be applied to a subtype whose parent type has 9533a @code{Dimension_System} aspect. The aspect must specify values for 9534all dimensions of the system. The rational values are the powers of the 9535corresponding dimensions that are used by the compiler to verify that 9536physical (numeric) computations are dimensionally consistent. For example, 9537the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 9538For further examples of the usage 9539of this aspect, see package @code{System.Dim.Mks}. 9540Note that when the dimensioned type is an integer type, then any 9541dimension value must be an integer literal. 9542 9543@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 9544@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{131} 9545@section Aspect Dimension_System 9546 9547 9548@geindex Dimension_System 9549 9550The @code{Dimension_System} aspect is used to define a system of 9551dimensions that will be used in subsequent subtype declarations with 9552@code{Dimension} aspects that reference this system. The syntax is: 9553 9554@example 9555with Dimension_System => (DIMENSION @{, DIMENSION@}); 9556 9557DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 9558 [Unit_Symbol =>] SYMBOL, 9559 [Dim_Symbol =>] SYMBOL) 9560 9561SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 9562@end example 9563 9564This aspect is applied to a type, which must be a numeric derived type 9565(typically a floating-point type), that 9566will represent values within the dimension system. Each @code{DIMENSION} 9567corresponds to one particular dimension. A maximum of 7 dimensions may 9568be specified. @code{Unit_Name} is the name of the dimension (for example 9569@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 9570of this dimension (for example @code{m} for @code{Meter}). 9571@code{Dim_Symbol} gives 9572the identification within the dimension system (typically this is a 9573single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 9574The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 9575The @code{Dim_Symbol} is used in error messages when numeric operations have 9576inconsistent dimensions. 9577 9578GNAT provides the standard definition of the International MKS system in 9579the run-time package @code{System.Dim.Mks}. You can easily define 9580similar packages for cgs units or British units, and define conversion factors 9581between values in different systems. The MKS system is characterized by the 9582following aspect: 9583 9584@example 9585type Mks_Type is new Long_Long_Float with 9586 Dimension_System => ( 9587 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 9588 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 9589 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 9590 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 9591 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 9592 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 9593 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 9594@end example 9595 9596Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to 9597represent a theta character (avoiding the use of extended Latin-1 9598characters in this context). 9599 9600See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users 9601Guide for detailed examples of use of the dimension system. 9602 9603@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 9604@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{132} 9605@section Aspect Disable_Controlled 9606 9607 9608@geindex Disable_Controlled 9609 9610The aspect @code{Disable_Controlled} is defined for controlled record types. If 9611active, this aspect causes suppression of all related calls to @code{Initialize}, 9612@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, 9613where for example you might want a record to be controlled or not depending on 9614whether some run-time check is enabled or suppressed. 9615 9616@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 9617@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{133} 9618@section Aspect Effective_Reads 9619 9620 9621@geindex Effective_Reads 9622 9623This aspect is equivalent to @ref{5c,,pragma Effective_Reads}. 9624 9625@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 9626@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{134} 9627@section Aspect Effective_Writes 9628 9629 9630@geindex Effective_Writes 9631 9632This aspect is equivalent to @ref{5e,,pragma Effective_Writes}. 9633 9634@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 9635@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{135} 9636@section Aspect Extensions_Visible 9637 9638 9639@geindex Extensions_Visible 9640 9641This aspect is equivalent to @ref{6a,,pragma Extensions_Visible}. 9642 9643@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 9644@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{136} 9645@section Aspect Favor_Top_Level 9646 9647 9648@geindex Favor_Top_Level 9649 9650This boolean aspect is equivalent to @ref{6f,,pragma Favor_Top_Level}. 9651 9652@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9653@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{137} 9654@section Aspect Ghost 9655 9656 9657@geindex Ghost 9658 9659This aspect is equivalent to @ref{72,,pragma Ghost}. 9660 9661@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9662@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{138} 9663@section Aspect Global 9664 9665 9666@geindex Global 9667 9668This aspect is equivalent to @ref{74,,pragma Global}. 9669 9670@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9671@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{139} 9672@section Aspect Initial_Condition 9673 9674 9675@geindex Initial_Condition 9676 9677This aspect is equivalent to @ref{82,,pragma Initial_Condition}. 9678 9679@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9680@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{13a} 9681@section Aspect Initializes 9682 9683 9684@geindex Initializes 9685 9686This aspect is equivalent to @ref{84,,pragma Initializes}. 9687 9688@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9689@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{13b} 9690@section Aspect Inline_Always 9691 9692 9693@geindex Inline_Always 9694 9695This boolean aspect is equivalent to @ref{87,,pragma Inline_Always}. 9696 9697@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects 9698@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{13c} 9699@section Aspect Invariant 9700 9701 9702@geindex Invariant 9703 9704This aspect is equivalent to @ref{8e,,pragma Invariant}. It is a 9705synonym for the language defined aspect @code{Type_Invariant} except 9706that it is separately controllable using pragma @code{Assertion_Policy}. 9707 9708@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9709@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13d} 9710@section Aspect Invariant'Class 9711 9712 9713@geindex Invariant'Class 9714 9715This aspect is equivalent to @ref{106,,pragma Type_Invariant_Class}. It is a 9716synonym for the language defined aspect @code{Type_Invariant'Class} except 9717that it is separately controllable using pragma @code{Assertion_Policy}. 9718 9719@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects 9720@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13e} 9721@section Aspect Iterable 9722 9723 9724@geindex Iterable 9725 9726This aspect provides a light-weight mechanism for loops and quantified 9727expressions over container types, without the overhead imposed by the tampering 9728checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9729with six named components, of which the last three are optional: @code{First}, 9730@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. 9731When only the first three components are specified, only the 9732@code{for .. in} form of iteration over cursors is available. When @code{Element} 9733is specified, both this form and the @code{for .. of} form of iteration over 9734elements are available. If the last two components are specified, reverse 9735iterations over the container can be specified (analogous to what can be done 9736over predefined containers that support the @code{Reverse_Iterator} interface). 9737The following is a typical example of use: 9738 9739@example 9740type List is private with 9741 Iterable => (First => First_Cursor, 9742 Next => Advance, 9743 Has_Element => Cursor_Has_Element, 9744 [Element => Get_Element]); 9745@end example 9746 9747 9748@itemize * 9749 9750@item 9751The value denoted by @code{First} must denote a primitive operation of the 9752container type that returns a @code{Cursor}, which must a be a type declared in 9753the container package or visible from it. For example: 9754@end itemize 9755 9756@example 9757function First_Cursor (Cont : Container) return Cursor; 9758@end example 9759 9760 9761@itemize * 9762 9763@item 9764The value of @code{Next} is a primitive operation of the container type that takes 9765both a container and a cursor and yields a cursor. For example: 9766@end itemize 9767 9768@example 9769function Advance (Cont : Container; Position : Cursor) return Cursor; 9770@end example 9771 9772 9773@itemize * 9774 9775@item 9776The value of @code{Has_Element} is a primitive operation of the container type 9777that takes both a container and a cursor and yields a boolean. For example: 9778@end itemize 9779 9780@example 9781function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9782@end example 9783 9784 9785@itemize * 9786 9787@item 9788The value of @code{Element} is a primitive operation of the container type that 9789takes both a container and a cursor and yields an @code{Element_Type}, which must 9790be a type declared in the container package or visible from it. For example: 9791@end itemize 9792 9793@example 9794function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9795@end example 9796 9797This aspect is used in the GNAT-defined formal container packages. 9798 9799@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9800@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13f} 9801@section Aspect Linker_Section 9802 9803 9804@geindex Linker_Section 9805 9806This aspect is equivalent to @ref{96,,pragma Linker_Section}. 9807 9808@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects 9809@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{140} 9810@section Aspect Lock_Free 9811 9812 9813@geindex Lock_Free 9814 9815This boolean aspect is equivalent to @ref{98,,pragma Lock_Free}. 9816 9817@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects 9818@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{141} 9819@section Aspect Max_Queue_Length 9820 9821 9822@geindex Max_Queue_Length 9823 9824This aspect is equivalent to @ref{a0,,pragma Max_Queue_Length}. 9825 9826@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects 9827@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{142} 9828@section Aspect No_Caching 9829 9830 9831@geindex No_Caching 9832 9833This boolean aspect is equivalent to @ref{a2,,pragma No_Caching}. 9834 9835@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects 9836@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{143} 9837@section Aspect No_Elaboration_Code_All 9838 9839 9840@geindex No_Elaboration_Code_All 9841 9842This aspect is equivalent to @ref{a6,,pragma No_Elaboration_Code_All} 9843for a program unit. 9844 9845@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9846@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{144} 9847@section Aspect No_Inline 9848 9849 9850@geindex No_Inline 9851 9852This boolean aspect is equivalent to @ref{a9,,pragma No_Inline}. 9853 9854@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects 9855@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{145} 9856@section Aspect No_Tagged_Streams 9857 9858 9859@geindex No_Tagged_Streams 9860 9861This aspect is equivalent to @ref{ac,,pragma No_Tagged_Streams} with an 9862argument specifying a root tagged type (thus this aspect can only be 9863applied to such a type). 9864 9865@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects 9866@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{146} 9867@section Aspect Object_Size 9868 9869 9870@geindex Object_Size 9871 9872This aspect is equivalent to @ref{147,,attribute Object_Size}. 9873 9874@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9875@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{148} 9876@section Aspect Obsolescent 9877 9878 9879@geindex Obsolsecent 9880 9881This aspect is equivalent to @ref{af,,pragma Obsolescent}. Note that the 9882evaluation of this aspect happens at the point of occurrence, it is not 9883delayed until the freeze point. 9884 9885@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9886@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{149} 9887@section Aspect Part_Of 9888 9889 9890@geindex Part_Of 9891 9892This aspect is equivalent to @ref{b7,,pragma Part_Of}. 9893 9894@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9895@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{14a} 9896@section Aspect Persistent_BSS 9897 9898 9899@geindex Persistent_BSS 9900 9901This boolean aspect is equivalent to @ref{ba,,pragma Persistent_BSS}. 9902 9903@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9904@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{14b} 9905@section Aspect Predicate 9906 9907 9908@geindex Predicate 9909 9910This aspect is equivalent to @ref{c2,,pragma Predicate}. It is thus 9911similar to the language defined aspects @code{Dynamic_Predicate} 9912and @code{Static_Predicate} except that whether the resulting 9913predicate is static or dynamic is controlled by the form of the 9914expression. It is also separately controllable using pragma 9915@code{Assertion_Policy}. 9916 9917@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9918@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{14c} 9919@section Aspect Pure_Function 9920 9921 9922@geindex Pure_Function 9923 9924This boolean aspect is equivalent to @ref{ce,,pragma Pure_Function}. 9925 9926@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9927@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{14d} 9928@section Aspect Refined_Depends 9929 9930 9931@geindex Refined_Depends 9932 9933This aspect is equivalent to @ref{d2,,pragma Refined_Depends}. 9934 9935@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9936@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14e} 9937@section Aspect Refined_Global 9938 9939 9940@geindex Refined_Global 9941 9942This aspect is equivalent to @ref{d4,,pragma Refined_Global}. 9943 9944@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9945@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14f} 9946@section Aspect Refined_Post 9947 9948 9949@geindex Refined_Post 9950 9951This aspect is equivalent to @ref{d6,,pragma Refined_Post}. 9952 9953@node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects 9954@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{150} 9955@section Aspect Refined_State 9956 9957 9958@geindex Refined_State 9959 9960This aspect is equivalent to @ref{d8,,pragma Refined_State}. 9961 9962@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Refined_State,Implementation Defined Aspects 9963@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{151} 9964@section Aspect Remote_Access_Type 9965 9966 9967@geindex Remote_Access_Type 9968 9969This aspect is equivalent to @ref{dc,,pragma Remote_Access_Type}. 9970 9971@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects 9972@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{152} 9973@section Aspect Secondary_Stack_Size 9974 9975 9976@geindex Secondary_Stack_Size 9977 9978This aspect is equivalent to @ref{e1,,pragma Secondary_Stack_Size}. 9979 9980@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects 9981@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{153} 9982@section Aspect Scalar_Storage_Order 9983 9984 9985@geindex Scalar_Storage_Order 9986 9987This aspect is equivalent to a @ref{154,,attribute Scalar_Storage_Order}. 9988 9989@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 9990@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{155} 9991@section Aspect Shared 9992 9993 9994@geindex Shared 9995 9996This boolean aspect is equivalent to @ref{e4,,pragma Shared} 9997and is thus a synonym for aspect @code{Atomic}. 9998 9999@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 10000@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{156} 10001@section Aspect Simple_Storage_Pool 10002 10003 10004@geindex Simple_Storage_Pool 10005 10006This aspect is equivalent to @ref{e9,,attribute Simple_Storage_Pool}. 10007 10008@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 10009@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{157} 10010@section Aspect Simple_Storage_Pool_Type 10011 10012 10013@geindex Simple_Storage_Pool_Type 10014 10015This boolean aspect is equivalent to @ref{e7,,pragma Simple_Storage_Pool_Type}. 10016 10017@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 10018@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{158} 10019@section Aspect SPARK_Mode 10020 10021 10022@geindex SPARK_Mode 10023 10024This aspect is equivalent to @ref{ef,,pragma SPARK_Mode} and 10025may be specified for either or both of the specification and body 10026of a subprogram or package. 10027 10028@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 10029@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{159} 10030@section Aspect Suppress_Debug_Info 10031 10032 10033@geindex Suppress_Debug_Info 10034 10035This boolean aspect is equivalent to @ref{f7,,pragma Suppress_Debug_Info}. 10036 10037@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 10038@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{15a} 10039@section Aspect Suppress_Initialization 10040 10041 10042@geindex Suppress_Initialization 10043 10044This boolean aspect is equivalent to @ref{fb,,pragma Suppress_Initialization}. 10045 10046@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 10047@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{15b} 10048@section Aspect Test_Case 10049 10050 10051@geindex Test_Case 10052 10053This aspect is equivalent to @ref{fe,,pragma Test_Case}. 10054 10055@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 10056@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{15c} 10057@section Aspect Thread_Local_Storage 10058 10059 10060@geindex Thread_Local_Storage 10061 10062This boolean aspect is equivalent to @ref{100,,pragma Thread_Local_Storage}. 10063 10064@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects 10065@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{15d} 10066@section Aspect Universal_Aliasing 10067 10068 10069@geindex Universal_Aliasing 10070 10071This boolean aspect is equivalent to @ref{10a,,pragma Universal_Aliasing}. 10072 10073@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects 10074@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{15e} 10075@section Aspect Universal_Data 10076 10077 10078@geindex Universal_Data 10079 10080This aspect is equivalent to @ref{10c,,pragma Universal_Data}. 10081 10082@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects 10083@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15f} 10084@section Aspect Unmodified 10085 10086 10087@geindex Unmodified 10088 10089This boolean aspect is equivalent to @ref{10f,,pragma Unmodified}. 10090 10091@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 10092@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{160} 10093@section Aspect Unreferenced 10094 10095 10096@geindex Unreferenced 10097 10098This boolean aspect is equivalent to @ref{110,,pragma Unreferenced}. Note that 10099in the case of formal parameters, it is not permitted to have aspects for 10100a formal parameter, so in this case the pragma form must be used. 10101 10102@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 10103@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{161} 10104@section Aspect Unreferenced_Objects 10105 10106 10107@geindex Unreferenced_Objects 10108 10109This boolean aspect is equivalent to @ref{112,,pragma Unreferenced_Objects}. 10110 10111@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 10112@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{162} 10113@section Aspect Value_Size 10114 10115 10116@geindex Value_Size 10117 10118This aspect is equivalent to @ref{163,,attribute Value_Size}. 10119 10120@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 10121@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{164} 10122@section Aspect Volatile_Full_Access 10123 10124 10125@geindex Volatile_Full_Access 10126 10127This boolean aspect is equivalent to @ref{11d,,pragma Volatile_Full_Access}. 10128 10129@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 10130@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{165} 10131@section Aspect Volatile_Function 10132 10133 10134@geindex Volatile_Function 10135 10136This boolean aspect is equivalent to @ref{11f,,pragma Volatile_Function}. 10137 10138@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 10139@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{166} 10140@section Aspect Warnings 10141 10142 10143@geindex Warnings 10144 10145This aspect is equivalent to the two argument form of @ref{121,,pragma Warnings}, 10146where the first argument is @code{ON} or @code{OFF} and the second argument 10147is the entity. 10148 10149@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 10150@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{167}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{168} 10151@chapter Implementation Defined Attributes 10152 10153 10154Ada defines (throughout the Ada reference manual, 10155summarized in Annex K), 10156a set of attributes that provide useful additional functionality in all 10157areas of the language. These language defined attributes are implemented 10158in GNAT and work as described in the Ada Reference Manual. 10159 10160In addition, Ada allows implementations to define additional 10161attributes whose meaning is defined by the implementation. GNAT provides 10162a number of these implementation-dependent attributes which can be used 10163to extend and enhance the functionality of the compiler. This section of 10164the GNAT reference manual describes these additional attributes. It also 10165describes additional implementation-dependent features of standard 10166language-defined attributes. 10167 10168Note that any program using these attributes may not be portable to 10169other compilers (although GNAT implements this set of attributes on all 10170platforms). Therefore if portability to other compilers is an important 10171consideration, you should minimize the use of these attributes. 10172 10173@menu 10174* Attribute Abort_Signal:: 10175* Attribute Address_Size:: 10176* Attribute Asm_Input:: 10177* Attribute Asm_Output:: 10178* Attribute Atomic_Always_Lock_Free:: 10179* Attribute Bit:: 10180* Attribute Bit_Position:: 10181* Attribute Code_Address:: 10182* Attribute Compiler_Version:: 10183* Attribute Constrained:: 10184* Attribute Default_Bit_Order:: 10185* Attribute Default_Scalar_Storage_Order:: 10186* Attribute Deref:: 10187* Attribute Descriptor_Size:: 10188* Attribute Elaborated:: 10189* Attribute Elab_Body:: 10190* Attribute Elab_Spec:: 10191* Attribute Elab_Subp_Body:: 10192* Attribute Emax:: 10193* Attribute Enabled:: 10194* Attribute Enum_Rep:: 10195* Attribute Enum_Val:: 10196* Attribute Epsilon:: 10197* Attribute Fast_Math:: 10198* Attribute Finalization_Size:: 10199* Attribute Fixed_Value:: 10200* Attribute From_Any:: 10201* Attribute Has_Access_Values:: 10202* Attribute Has_Discriminants:: 10203* Attribute Img:: 10204* Attribute Integer_Value:: 10205* Attribute Invalid_Value:: 10206* Attribute Iterable:: 10207* Attribute Large:: 10208* Attribute Library_Level:: 10209* Attribute Lock_Free:: 10210* Attribute Loop_Entry:: 10211* Attribute Machine_Size:: 10212* Attribute Mantissa:: 10213* Attribute Maximum_Alignment:: 10214* Attribute Mechanism_Code:: 10215* Attribute Null_Parameter:: 10216* Attribute Object_Size:: 10217* Attribute Old:: 10218* Attribute Passed_By_Reference:: 10219* Attribute Pool_Address:: 10220* Attribute Range_Length:: 10221* Attribute Restriction_Set:: 10222* Attribute Result:: 10223* Attribute Safe_Emax:: 10224* Attribute Safe_Large:: 10225* Attribute Safe_Small:: 10226* Attribute Scalar_Storage_Order:: 10227* Attribute Simple_Storage_Pool:: 10228* Attribute Small:: 10229* Attribute Storage_Unit:: 10230* Attribute Stub_Type:: 10231* Attribute System_Allocator_Alignment:: 10232* Attribute Target_Name:: 10233* Attribute To_Address:: 10234* Attribute To_Any:: 10235* Attribute Type_Class:: 10236* Attribute Type_Key:: 10237* Attribute TypeCode:: 10238* Attribute Unconstrained_Array:: 10239* Attribute Universal_Literal_String:: 10240* Attribute Unrestricted_Access:: 10241* Attribute Update:: 10242* Attribute Valid_Scalars:: 10243* Attribute VADS_Size:: 10244* Attribute Value_Size:: 10245* Attribute Wchar_T_Size:: 10246* Attribute Word_Size:: 10247 10248@end menu 10249 10250@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 10251@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{169} 10252@section Attribute Abort_Signal 10253 10254 10255@geindex Abort_Signal 10256 10257@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 10258prefix) provides the entity for the special exception used to signal 10259task abort or asynchronous transfer of control. Normally this attribute 10260should only be used in the tasking runtime (it is highly peculiar, and 10261completely outside the normal semantics of Ada, for a user program to 10262intercept the abort exception). 10263 10264@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 10265@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{16a} 10266@section Attribute Address_Size 10267 10268 10269@geindex Size of `@w{`}Address`@w{`} 10270 10271@geindex Address_Size 10272 10273@code{Standard'Address_Size} (@code{Standard} is the only allowed 10274prefix) is a static constant giving the number of bits in an 10275@code{Address}. It is the same value as System.Address'Size, 10276but has the advantage of being static, while a direct 10277reference to System.Address'Size is nonstatic because Address 10278is a private type. 10279 10280@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 10281@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{16b} 10282@section Attribute Asm_Input 10283 10284 10285@geindex Asm_Input 10286 10287The @code{Asm_Input} attribute denotes a function that takes two 10288parameters. The first is a string, the second is an expression of the 10289type designated by the prefix. The first (string) argument is required 10290to be a static expression, and is the constraint for the parameter, 10291(e.g., what kind of register is required). The second argument is the 10292value to be used as the input argument. The possible values for the 10293constant are the same as those used in the RTL, and are dependent on 10294the configuration file used to built the GCC back end. 10295@ref{16c,,Machine Code Insertions} 10296 10297@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 10298@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{16d} 10299@section Attribute Asm_Output 10300 10301 10302@geindex Asm_Output 10303 10304The @code{Asm_Output} attribute denotes a function that takes two 10305parameters. The first is a string, the second is the name of a variable 10306of the type designated by the attribute prefix. The first (string) 10307argument is required to be a static expression and designates the 10308constraint for the parameter (e.g., what kind of register is 10309required). The second argument is the variable to be updated with the 10310result. The possible values for constraint are the same as those used in 10311the RTL, and are dependent on the configuration file used to build the 10312GCC back end. If there are no output operands, then this argument may 10313either be omitted, or explicitly given as @code{No_Output_Operands}. 10314@ref{16c,,Machine Code Insertions} 10315 10316@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 10317@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16e} 10318@section Attribute Atomic_Always_Lock_Free 10319 10320 10321@geindex Atomic_Always_Lock_Free 10322 10323The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. 10324The result is a Boolean value which is True if the type has discriminants, 10325and False otherwise. The result indicate whether atomic operations are 10326supported by the target for the given type. 10327 10328@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 10329@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16f} 10330@section Attribute Bit 10331 10332 10333@geindex Bit 10334 10335@code{obj'Bit}, where @code{obj} is any object, yields the bit 10336offset within the storage unit (byte) that contains the first bit of 10337storage allocated for the object. The value of this attribute is of the 10338type @emph{universal_integer}, and is always a non-negative number not 10339exceeding the value of @code{System.Storage_Unit}. 10340 10341For an object that is a variable or a constant allocated in a register, 10342the value is zero. (The use of this attribute does not force the 10343allocation of a variable to memory). 10344 10345For an object that is a formal parameter, this attribute applies 10346to either the matching actual parameter or to a copy of the 10347matching actual parameter. 10348 10349For an access object the value is zero. Note that 10350@code{obj.all'Bit} is subject to an @code{Access_Check} for the 10351designated object. Similarly for a record component 10352@code{X.C'Bit} is subject to a discriminant check and 10353@code{X(I).Bit} and @code{X(I1..I2)'Bit} 10354are subject to index checks. 10355 10356This attribute is designed to be compatible with the DEC Ada 83 definition 10357and implementation of the @code{Bit} attribute. 10358 10359@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 10360@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{170} 10361@section Attribute Bit_Position 10362 10363 10364@geindex Bit_Position 10365 10366@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one 10367of the fields of the record type, yields the bit 10368offset within the record contains the first bit of 10369storage allocated for the object. The value of this attribute is of the 10370type @emph{universal_integer}. The value depends only on the field 10371@code{C} and is independent of the alignment of 10372the containing record @code{R}. 10373 10374@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 10375@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{171} 10376@section Attribute Code_Address 10377 10378 10379@geindex Code_Address 10380 10381@geindex Subprogram address 10382 10383@geindex Address of subprogram code 10384 10385The @code{'Address} 10386attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 10387intended effect seems to be to provide 10388an address value which can be used to call the subprogram by means of 10389an address clause as in the following example: 10390 10391@example 10392procedure K is ... 10393 10394procedure L; 10395for L'Address use K'Address; 10396pragma Import (Ada, L); 10397@end example 10398 10399A call to @code{L} is then expected to result in a call to @code{K}. 10400In Ada 83, where there were no access-to-subprogram values, this was 10401a common work-around for getting the effect of an indirect call. 10402GNAT implements the above use of @code{Address} and the technique 10403illustrated by the example code works correctly. 10404 10405However, for some purposes, it is useful to have the address of the start 10406of the generated code for the subprogram. On some architectures, this is 10407not necessarily the same as the @code{Address} value described above. 10408For example, the @code{Address} value may reference a subprogram 10409descriptor rather than the subprogram itself. 10410 10411The @code{'Code_Address} attribute, which can only be applied to 10412subprogram entities, always returns the address of the start of the 10413generated code of the specified subprogram, which may or may not be 10414the same value as is returned by the corresponding @code{'Address} 10415attribute. 10416 10417@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 10418@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{172} 10419@section Attribute Compiler_Version 10420 10421 10422@geindex Compiler_Version 10423 10424@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 10425prefix) yields a static string identifying the version of the compiler 10426being used to compile the unit containing the attribute reference. 10427 10428@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 10429@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{173} 10430@section Attribute Constrained 10431 10432 10433@geindex Constrained 10434 10435In addition to the usage of this attribute in the Ada RM, GNAT 10436also permits the use of the @code{'Constrained} attribute 10437in a generic template 10438for any type, including types without discriminants. The value of this 10439attribute in the generic instance when applied to a scalar type or a 10440record type without discriminants is always @code{True}. This usage is 10441compatible with older Ada compilers, including notably DEC Ada. 10442 10443@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 10444@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{174} 10445@section Attribute Default_Bit_Order 10446 10447 10448@geindex Big endian 10449 10450@geindex Little endian 10451 10452@geindex Default_Bit_Order 10453 10454@code{Standard'Default_Bit_Order} (@code{Standard} is the only 10455permissible prefix), provides the value @code{System.Default_Bit_Order} 10456as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 10457@code{Low_Order_First}). This is used to construct the definition of 10458@code{Default_Bit_Order} in package @code{System}. 10459 10460@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 10461@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{175} 10462@section Attribute Default_Scalar_Storage_Order 10463 10464 10465@geindex Big endian 10466 10467@geindex Little endian 10468 10469@geindex Default_Scalar_Storage_Order 10470 10471@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only 10472permissible prefix), provides the current value of the default scalar storage 10473order (as specified using pragma @code{Default_Scalar_Storage_Order}, or 10474equal to @code{Default_Bit_Order} if unspecified) as a 10475@code{System.Bit_Order} value. This is a static attribute. 10476 10477@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 10478@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{176} 10479@section Attribute Deref 10480 10481 10482@geindex Deref 10483 10484The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields 10485the variable of type @code{typ} that is located at the given address. It is similar 10486to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to 10487a named access-to-@cite{typ} type, except that it yields a variable, so it can be 10488used on the left side of an assignment. 10489 10490@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 10491@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{177} 10492@section Attribute Descriptor_Size 10493 10494 10495@geindex Descriptor 10496 10497@geindex Dope vector 10498 10499@geindex Descriptor_Size 10500 10501Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the 10502descriptor allocated for a type. The result is non-zero only for unconstrained 10503array types and the returned value is of type universal integer. In GNAT, an 10504array descriptor contains bounds information and is located immediately before 10505the first element of the array. 10506 10507@example 10508type Unconstr_Array is array (Positive range <>) of Boolean; 10509Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 10510@end example 10511 10512The attribute takes into account any additional padding due to type alignment. 10513In the example above, the descriptor contains two values of type 10514@code{Positive} representing the low and high bound. Since @code{Positive} has 10515a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * Positive'Size + 2} or 64 bits. 10516 10517@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 10518@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{178} 10519@section Attribute Elaborated 10520 10521 10522@geindex Elaborated 10523 10524The prefix of the @code{'Elaborated} attribute must be a unit name. The 10525value is a Boolean which indicates whether or not the given unit has been 10526elaborated. This attribute is primarily intended for internal use by the 10527generated code for dynamic elaboration checking, but it can also be used 10528in user programs. The value will always be True once elaboration of all 10529units has been completed. An exception is for units which need no 10530elaboration, the value is always False for such units. 10531 10532@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 10533@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{179} 10534@section Attribute Elab_Body 10535 10536 10537@geindex Elab_Body 10538 10539This attribute can only be applied to a program unit name. It returns 10540the entity for the corresponding elaboration procedure for elaborating 10541the body of the referenced unit. This is used in the main generated 10542elaboration procedure by the binder and is not normally used in any 10543other context. However, there may be specialized situations in which it 10544is useful to be able to call this elaboration procedure from Ada code, 10545e.g., if it is necessary to do selective re-elaboration to fix some 10546error. 10547 10548@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 10549@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{17a} 10550@section Attribute Elab_Spec 10551 10552 10553@geindex Elab_Spec 10554 10555This attribute can only be applied to a program unit name. It returns 10556the entity for the corresponding elaboration procedure for elaborating 10557the spec of the referenced unit. This is used in the main 10558generated elaboration procedure by the binder and is not normally used 10559in any other context. However, there may be specialized situations in 10560which it is useful to be able to call this elaboration procedure from 10561Ada code, e.g., if it is necessary to do selective re-elaboration to fix 10562some error. 10563 10564@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 10565@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{17b} 10566@section Attribute Elab_Subp_Body 10567 10568 10569@geindex Elab_Subp_Body 10570 10571This attribute can only be applied to a library level subprogram 10572name and is only allowed in CodePeer mode. It returns the entity 10573for the corresponding elaboration procedure for elaborating the body 10574of the referenced subprogram unit. This is used in the main generated 10575elaboration procedure by the binder in CodePeer mode only and is unrecognized 10576otherwise. 10577 10578@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 10579@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{17c} 10580@section Attribute Emax 10581 10582 10583@geindex Ada 83 attributes 10584 10585@geindex Emax 10586 10587The @code{Emax} attribute is provided for compatibility with Ada 83. See 10588the Ada 83 reference manual for an exact description of the semantics of 10589this attribute. 10590 10591@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 10592@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{17d} 10593@section Attribute Enabled 10594 10595 10596@geindex Enabled 10597 10598The @code{Enabled} attribute allows an application program to check at compile 10599time to see if the designated check is currently enabled. The prefix is a 10600simple identifier, referencing any predefined check name (other than 10601@code{All_Checks}) or a check name introduced by pragma Check_Name. If 10602no argument is given for the attribute, the check is for the general state 10603of the check, if an argument is given, then it is an entity name, and the 10604check indicates whether an @code{Suppress} or @code{Unsuppress} has been 10605given naming the entity (if not, then the argument is ignored). 10606 10607Note that instantiations inherit the check status at the point of the 10608instantiation, so a useful idiom is to have a library package that 10609introduces a check name with @code{pragma Check_Name}, and then contains 10610generic packages or subprograms which use the @code{Enabled} attribute 10611to see if the check is enabled. A user of this package can then issue 10612a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 10613the package or subprogram, controlling whether the check will be present. 10614 10615@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 10616@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17e} 10617@section Attribute Enum_Rep 10618 10619 10620@geindex Representation of enums 10621 10622@geindex Enum_Rep 10623 10624For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a 10625function with the following spec: 10626 10627@example 10628function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 10629@end example 10630 10631It is also allowable to apply @code{Enum_Rep} directly to an object of an 10632enumeration type or to a non-overloaded enumeration 10633literal. In this case @code{S'Enum_Rep} is equivalent to 10634@code{typ'Enum_Rep(S)} where @code{typ} is the type of the 10635enumeration literal or object. 10636 10637The function returns the representation value for the given enumeration 10638value. This will be equal to value of the @code{Pos} attribute in the 10639absence of an enumeration representation clause. This is a static 10640attribute (i.e.,:the result is static if the argument is static). 10641 10642@code{S'Enum_Rep} can also be used with integer types and objects, 10643in which case it simply returns the integer value. The reason for this 10644is to allow it to be used for @code{(<>)} discrete formal arguments in 10645a generic unit that can be instantiated with either enumeration types 10646or integer types. Note that if @code{Enum_Rep} is used on a modular 10647type whose upper bound exceeds the upper bound of the largest signed 10648integer type, and the argument is a variable, so that the universal 10649integer calculation is done at run time, then the call to @code{Enum_Rep} 10650may raise @code{Constraint_Error}. 10651 10652@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 10653@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17f} 10654@section Attribute Enum_Val 10655 10656 10657@geindex Representation of enums 10658 10659@geindex Enum_Val 10660 10661For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a 10662function with the following spec: 10663 10664@example 10665function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 10666@end example 10667 10668The function returns the enumeration value whose representation matches the 10669argument, or raises Constraint_Error if no enumeration literal of the type 10670has the matching value. 10671This will be equal to value of the @code{Val} attribute in the 10672absence of an enumeration representation clause. This is a static 10673attribute (i.e., the result is static if the argument is static). 10674 10675@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 10676@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{180} 10677@section Attribute Epsilon 10678 10679 10680@geindex Ada 83 attributes 10681 10682@geindex Epsilon 10683 10684The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 10685the Ada 83 reference manual for an exact description of the semantics of 10686this attribute. 10687 10688@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes 10689@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{181} 10690@section Attribute Fast_Math 10691 10692 10693@geindex Fast_Math 10694 10695@code{Standard'Fast_Math} (@code{Standard} is the only allowed 10696prefix) yields a static Boolean value that is True if pragma 10697@code{Fast_Math} is active, and False otherwise. 10698 10699@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes 10700@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{182} 10701@section Attribute Finalization_Size 10702 10703 10704@geindex Finalization_Size 10705 10706The prefix of attribute @code{Finalization_Size} must be an object or 10707a non-class-wide type. This attribute returns the size of any hidden data 10708reserved by the compiler to handle finalization-related actions. The type of 10709the attribute is @emph{universal_integer}. 10710 10711@code{Finalization_Size} yields a value of zero for a type with no controlled 10712parts, an object whose type has no controlled parts, or an object of a 10713class-wide type whose tag denotes a type with no controlled parts. 10714 10715Note that only heap-allocated objects contain finalization data. 10716 10717@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes 10718@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{183} 10719@section Attribute Fixed_Value 10720 10721 10722@geindex Fixed_Value 10723 10724For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a 10725function with the following specification: 10726 10727@example 10728function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10729@end example 10730 10731The value returned is the fixed-point value @code{V} such that: 10732 10733@example 10734V = Arg * S'Small 10735@end example 10736 10737The effect is thus similar to first converting the argument to the 10738integer type used to represent @code{S}, and then doing an unchecked 10739conversion to the fixed-point type. The difference is 10740that there are full range checks, to ensure that the result is in range. 10741This attribute is primarily intended for use in implementation of the 10742input-output functions for fixed-point values. 10743 10744@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10745@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{184} 10746@section Attribute From_Any 10747 10748 10749@geindex From_Any 10750 10751This internal attribute is used for the generation of remote subprogram 10752stubs in the context of the Distributed Systems Annex. 10753 10754@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10755@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{185} 10756@section Attribute Has_Access_Values 10757 10758 10759@geindex Access values 10760@geindex testing for 10761 10762@geindex Has_Access_Values 10763 10764The prefix of the @code{Has_Access_Values} attribute is a type. The result 10765is a Boolean value which is True if the is an access type, or is a composite 10766type with a component (at any nesting depth) that is an access type, and is 10767False otherwise. 10768The intended use of this attribute is in conjunction with generic 10769definitions. If the attribute is applied to a generic private type, it 10770indicates whether or not the corresponding actual type has access values. 10771 10772@node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes 10773@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{186} 10774@section Attribute Has_Discriminants 10775 10776 10777@geindex Discriminants 10778@geindex testing for 10779 10780@geindex Has_Discriminants 10781 10782The prefix of the @code{Has_Discriminants} attribute is a type. The result 10783is a Boolean value which is True if the type has discriminants, and False 10784otherwise. The intended use of this attribute is in conjunction with generic 10785definitions. If the attribute is applied to a generic private type, it 10786indicates whether or not the corresponding actual type has discriminants. 10787 10788@node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes 10789@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{187} 10790@section Attribute Img 10791 10792 10793@geindex Img 10794 10795The @code{Img} attribute differs from @code{Image} in that, while both can be 10796applied directly to an object, @code{Img} cannot be applied to types. 10797 10798Example usage of the attribute: 10799 10800@example 10801Put_Line ("X = " & X'Img); 10802@end example 10803 10804which has the same meaning as the more verbose: 10805 10806@example 10807Put_Line ("X = " & T'Image (X)); 10808@end example 10809 10810where @code{T} is the (sub)type of the object @code{X}. 10811 10812Note that technically, in analogy to @code{Image}, 10813@code{X'Img} returns a parameterless function 10814that returns the appropriate string when called. This means that 10815@code{X'Img} can be renamed as a function-returning-string, or used 10816in an instantiation as a function parameter. 10817 10818@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes 10819@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{188} 10820@section Attribute Integer_Value 10821 10822 10823@geindex Integer_Value 10824 10825For every integer type @code{S}, @code{S'Integer_Value} denotes a 10826function with the following spec: 10827 10828@example 10829function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10830@end example 10831 10832The value returned is the integer value @code{V}, such that: 10833 10834@example 10835Arg = V * T'Small 10836@end example 10837 10838where @code{T} is the type of @code{Arg}. 10839The effect is thus similar to first doing an unchecked conversion from 10840the fixed-point type to its corresponding implementation type, and then 10841converting the result to the target integer type. The difference is 10842that there are full range checks, to ensure that the result is in range. 10843This attribute is primarily intended for use in implementation of the 10844standard input-output functions for fixed-point values. 10845 10846@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10847@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{189} 10848@section Attribute Invalid_Value 10849 10850 10851@geindex Invalid_Value 10852 10853For every scalar type S, S'Invalid_Value returns an undefined value of the 10854type. If possible this value is an invalid representation for the type. The 10855value returned is identical to the value used to initialize an otherwise 10856uninitialized value of the type if pragma Initialize_Scalars is used, 10857including the ability to modify the value with the binder -Sxx flag and 10858relevant environment variables at run time. 10859 10860@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10861@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{18a} 10862@section Attribute Iterable 10863 10864 10865@geindex Iterable 10866 10867Equivalent to Aspect Iterable. 10868 10869@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10870@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{18b} 10871@section Attribute Large 10872 10873 10874@geindex Ada 83 attributes 10875 10876@geindex Large 10877 10878The @code{Large} attribute is provided for compatibility with Ada 83. See 10879the Ada 83 reference manual for an exact description of the semantics of 10880this attribute. 10881 10882@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10883@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{18c} 10884@section Attribute Library_Level 10885 10886 10887@geindex Library_Level 10888 10889@code{P'Library_Level}, where P is an entity name, 10890returns a Boolean value which is True if the entity is declared 10891at the library level, and False otherwise. Note that within a 10892generic instantition, the name of the generic unit denotes the 10893instance, which means that this attribute can be used to test 10894if a generic is instantiated at the library level, as shown 10895in this example: 10896 10897@example 10898generic 10899 ... 10900package Gen is 10901 pragma Compile_Time_Error 10902 (not Gen'Library_Level, 10903 "Gen can only be instantiated at library level"); 10904 ... 10905end Gen; 10906@end example 10907 10908@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10909@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18d} 10910@section Attribute Lock_Free 10911 10912 10913@geindex Lock_Free 10914 10915@code{P'Lock_Free}, where P is a protected object, returns True if a 10916pragma @code{Lock_Free} applies to P. 10917 10918@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 10919@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18e} 10920@section Attribute Loop_Entry 10921 10922 10923@geindex Loop_Entry 10924 10925Syntax: 10926 10927@example 10928X'Loop_Entry [(loop_name)] 10929@end example 10930 10931The @code{Loop_Entry} attribute is used to refer to the value that an 10932expression had upon entry to a given loop in much the same way that the 10933@code{Old} attribute in a subprogram postcondition can be used to refer 10934to the value an expression had upon entry to the subprogram. The 10935relevant loop is either identified by the given loop name, or it is the 10936innermost enclosing loop when no loop name is given. 10937 10938A @code{Loop_Entry} attribute can only occur within a 10939@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 10940@code{Loop_Entry} is to compare the current value of objects with their 10941initial value at loop entry, in a @code{Loop_Invariant} pragma. 10942 10943The effect of using @code{X'Loop_Entry} is the same as declaring 10944a constant initialized with the initial value of @code{X} at loop 10945entry. This copy is not performed if the loop is not entered, or if the 10946corresponding pragmas are ignored or disabled. 10947 10948@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 10949@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18f} 10950@section Attribute Machine_Size 10951 10952 10953@geindex Machine_Size 10954 10955This attribute is identical to the @code{Object_Size} attribute. It is 10956provided for compatibility with the DEC Ada 83 attribute of this name. 10957 10958@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 10959@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{190} 10960@section Attribute Mantissa 10961 10962 10963@geindex Ada 83 attributes 10964 10965@geindex Mantissa 10966 10967The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 10968the Ada 83 reference manual for an exact description of the semantics of 10969this attribute. 10970 10971@node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes 10972@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{191}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{192} 10973@section Attribute Maximum_Alignment 10974 10975 10976@geindex Alignment 10977@geindex maximum 10978 10979@geindex Maximum_Alignment 10980 10981@code{Standard'Maximum_Alignment} (@code{Standard} is the only 10982permissible prefix) provides the maximum useful alignment value for the 10983target. This is a static value that can be used to specify the alignment 10984for an object, guaranteeing that it is properly aligned in all 10985cases. 10986 10987@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes 10988@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{193} 10989@section Attribute Mechanism_Code 10990 10991 10992@geindex Return values 10993@geindex passing mechanism 10994 10995@geindex Parameters 10996@geindex passing mechanism 10997 10998@geindex Mechanism_Code 10999 11000@code{func'Mechanism_Code} yields an integer code for the 11001mechanism used for the result of function @code{func}, and 11002@code{subprog'Mechanism_Code (n)} yields the mechanism 11003used for formal parameter number @emph{n} (a static integer value, with 1 11004meaning the first parameter) of subprogram @code{subprog}. The code returned is: 11005 11006 11007@table @asis 11008 11009@item @emph{1} 11010 11011by copy (value) 11012 11013@item @emph{2} 11014 11015by reference 11016@end table 11017 11018@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 11019@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{194} 11020@section Attribute Null_Parameter 11021 11022 11023@geindex Zero address 11024@geindex passing 11025 11026@geindex Null_Parameter 11027 11028A reference @code{T'Null_Parameter} denotes an imaginary object of 11029type or subtype @code{T} allocated at machine address zero. The attribute 11030is allowed only as the default expression of a formal parameter, or as 11031an actual expression of a subprogram call. In either case, the 11032subprogram must be imported. 11033 11034The identity of the object is represented by the address zero in the 11035argument list, independent of the passing mechanism (explicit or 11036default). 11037 11038This capability is needed to specify that a zero address should be 11039passed for a record or other composite object passed by reference. 11040There is no way of indicating this without the @code{Null_Parameter} 11041attribute. 11042 11043@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 11044@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{147}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{195} 11045@section Attribute Object_Size 11046 11047 11048@geindex Size 11049@geindex used for objects 11050 11051@geindex Object_Size 11052 11053The size of an object is not necessarily the same as the size of the type 11054of an object. This is because by default object sizes are increased to be 11055a multiple of the alignment of the object. For example, 11056@code{Natural'Size} is 1105731, but by default objects of type @code{Natural} will have a size of 32 bits. 11058Similarly, a record containing an integer and a character: 11059 11060@example 11061type Rec is record 11062 I : Integer; 11063 C : Character; 11064end record; 11065@end example 11066 11067will have a size of 40 (that is @code{Rec'Size} will be 40). The 11068alignment will be 4, because of the 11069integer field, and so the default size of record objects for this type 11070will be 64 (8 bytes). 11071 11072If the alignment of the above record is specified to be 1, then the 11073object size will be 40 (5 bytes). This is true by default, and also 11074an object size of 40 can be explicitly specified in this case. 11075 11076A consequence of this capability is that different object sizes can be 11077given to subtypes that would otherwise be considered in Ada to be 11078statically matching. But it makes no sense to consider such subtypes 11079as statically matching. Consequently, GNAT adds a rule 11080to the static matching rules that requires object sizes to match. 11081Consider this example: 11082 11083@example 11084 1. procedure BadAVConvert is 11085 2. type R is new Integer; 11086 3. subtype R1 is R range 1 .. 10; 11087 4. subtype R2 is R range 1 .. 10; 11088 5. for R1'Object_Size use 8; 11089 6. for R2'Object_Size use 16; 11090 7. type R1P is access all R1; 11091 8. type R2P is access all R2; 11092 9. R1PV : R1P := new R1'(4); 1109310. R2PV : R2P; 1109411. begin 1109512. R2PV := R2P (R1PV); 11096 | 11097 >>> target designated subtype not compatible with 11098 type "R1" defined at line 3 11099 1110013. end; 11101@end example 11102 11103In the absence of lines 5 and 6, 11104types @code{R1} and @code{R2} statically match and 11105hence the conversion on line 12 is legal. But since lines 5 and 6 11106cause the object sizes to differ, GNAT considers that types 11107@code{R1} and @code{R2} are not statically matching, and line 12 11108generates the diagnostic shown above. 11109 11110Similar additional checks are performed in other contexts requiring 11111statically matching subtypes. 11112 11113@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 11114@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{196} 11115@section Attribute Old 11116 11117 11118@geindex Old 11119 11120In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage 11121within @code{Post} aspect), GNAT also permits the use of this attribute 11122in implementation defined pragmas @code{Postcondition}, 11123@code{Contract_Cases} and @code{Test_Case}. Also usages of 11124@code{Old} which would be illegal according to the Ada 2012 RM 11125definition are allowed under control of 11126implementation defined pragma @code{Unevaluated_Use_Of_Old}. 11127 11128@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 11129@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{197} 11130@section Attribute Passed_By_Reference 11131 11132 11133@geindex Parameters 11134@geindex when passed by reference 11135 11136@geindex Passed_By_Reference 11137 11138@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns 11139a value of type @code{Boolean} value that is @code{True} if the type is 11140normally passed by reference and @code{False} if the type is normally 11141passed by copy in calls. For scalar types, the result is always @code{False} 11142and is static. For non-scalar types, the result is nonstatic. 11143 11144@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 11145@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{198} 11146@section Attribute Pool_Address 11147 11148 11149@geindex Parameters 11150@geindex when passed by reference 11151 11152@geindex Pool_Address 11153 11154@code{X'Pool_Address} for any object @code{X} returns the address 11155of X within its storage pool. This is the same as 11156@code{X'Address}, except that for an unconstrained array whose 11157bounds are allocated just before the first component, 11158@code{X'Pool_Address} returns the address of those bounds, 11159whereas @code{X'Address} returns the address of the first 11160component. 11161 11162Here, we are interpreting 'storage pool' broadly to mean 11163@code{wherever the object is allocated}, which could be a 11164user-defined storage pool, 11165the global heap, on the stack, or in a static memory area. 11166For an object created by @code{new}, @code{Ptr.all'Pool_Address} is 11167what is passed to @code{Allocate} and returned from @code{Deallocate}. 11168 11169@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 11170@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{199} 11171@section Attribute Range_Length 11172 11173 11174@geindex Range_Length 11175 11176@code{typ'Range_Length} for any discrete type @cite{typ} yields 11177the number of values represented by the subtype (zero for a null 11178range). The result is static for static subtypes. @code{Range_Length} 11179applied to the index subtype of a one dimensional array always gives the 11180same result as @code{Length} applied to the array itself. 11181 11182@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 11183@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{19a} 11184@section Attribute Restriction_Set 11185 11186 11187@geindex Restriction_Set 11188 11189@geindex Restrictions 11190 11191This attribute allows compile time testing of restrictions that 11192are currently in effect. It is primarily intended for specializing 11193code in the run-time based on restrictions that are active (e.g. 11194don't need to save fpt registers if restriction No_Floating_Point 11195is known to be in effect), but can be used anywhere. 11196 11197There are two forms: 11198 11199@example 11200System'Restriction_Set (partition_boolean_restriction_NAME) 11201System'Restriction_Set (No_Dependence => library_unit_NAME); 11202@end example 11203 11204In the case of the first form, the only restriction names 11205allowed are parameterless restrictions that are checked 11206for consistency at bind time. For a complete list see the 11207subtype @code{System.Rident.Partition_Boolean_Restrictions}. 11208 11209The result returned is True if the restriction is known to 11210be in effect, and False if the restriction is known not to 11211be in effect. An important guarantee is that the value of 11212a Restriction_Set attribute is known to be consistent throughout 11213all the code of a partition. 11214 11215This is trivially achieved if the entire partition is compiled 11216with a consistent set of restriction pragmas. However, the 11217compilation model does not require this. It is possible to 11218compile one set of units with one set of pragmas, and another 11219set of units with another set of pragmas. It is even possible 11220to compile a spec with one set of pragmas, and then WITH the 11221same spec with a different set of pragmas. Inconsistencies 11222in the actual use of the restriction are checked at bind time. 11223 11224In order to achieve the guarantee of consistency for the 11225Restriction_Set pragma, we consider that a use of the pragma 11226that yields False is equivalent to a violation of the 11227restriction. 11228 11229So for example if you write 11230 11231@example 11232if System'Restriction_Set (No_Floating_Point) then 11233 ... 11234else 11235 ... 11236end if; 11237@end example 11238 11239And the result is False, so that the else branch is executed, 11240you can assume that this restriction is not set for any unit 11241in the partition. This is checked by considering this use of 11242the restriction pragma to be a violation of the restriction 11243No_Floating_Point. This means that no other unit can attempt 11244to set this restriction (if some unit does attempt to set it, 11245the binder will refuse to bind the partition). 11246 11247Technical note: The restriction name and the unit name are 11248intepreted entirely syntactically, as in the corresponding 11249Restrictions pragma, they are not analyzed semantically, 11250so they do not have a type. 11251 11252@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 11253@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{19b} 11254@section Attribute Result 11255 11256 11257@geindex Result 11258 11259@code{function'Result} can only be used with in a Postcondition pragma 11260for a function. The prefix must be the name of the corresponding function. This 11261is used to refer to the result of the function in the postcondition expression. 11262For a further discussion of the use of this attribute and examples of its use, 11263see the description of pragma Postcondition. 11264 11265@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 11266@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19c} 11267@section Attribute Safe_Emax 11268 11269 11270@geindex Ada 83 attributes 11271 11272@geindex Safe_Emax 11273 11274The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 11275the Ada 83 reference manual for an exact description of the semantics of 11276this attribute. 11277 11278@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 11279@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19d} 11280@section Attribute Safe_Large 11281 11282 11283@geindex Ada 83 attributes 11284 11285@geindex Safe_Large 11286 11287The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 11288the Ada 83 reference manual for an exact description of the semantics of 11289this attribute. 11290 11291@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 11292@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19e} 11293@section Attribute Safe_Small 11294 11295 11296@geindex Ada 83 attributes 11297 11298@geindex Safe_Small 11299 11300The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See 11301the Ada 83 reference manual for an exact description of the semantics of 11302this attribute. 11303 11304@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 11305@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19f}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{154} 11306@section Attribute Scalar_Storage_Order 11307 11308 11309@geindex Endianness 11310 11311@geindex Scalar storage order 11312 11313@geindex Scalar_Storage_Order 11314 11315For every array or record type @code{S}, the representation attribute 11316@code{Scalar_Storage_Order} denotes the order in which storage elements 11317that make up scalar components are ordered within S. The value given must 11318be a static expression of type System.Bit_Order. The following is an example 11319of the use of this feature: 11320 11321@example 11322-- Component type definitions 11323 11324subtype Yr_Type is Natural range 0 .. 127; 11325subtype Mo_Type is Natural range 1 .. 12; 11326subtype Da_Type is Natural range 1 .. 31; 11327 11328-- Record declaration 11329 11330type Date is record 11331 Years_Since_1980 : Yr_Type; 11332 Month : Mo_Type; 11333 Day_Of_Month : Da_Type; 11334end record; 11335 11336-- Record representation clause 11337 11338for Date use record 11339 Years_Since_1980 at 0 range 0 .. 6; 11340 Month at 0 range 7 .. 10; 11341 Day_Of_Month at 0 range 11 .. 15; 11342end record; 11343 11344-- Attribute definition clauses 11345 11346for Date'Bit_Order use System.High_Order_First; 11347for Date'Scalar_Storage_Order use System.High_Order_First; 11348-- If Scalar_Storage_Order is specified, it must be consistent with 11349-- Bit_Order, so it's best to always define the latter explicitly if 11350-- the former is used. 11351@end example 11352 11353Other properties are as for the standard representation attribute @code{Bit_Order} 11354defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 11355 11356For a record type @code{T}, if @code{T'Scalar_Storage_Order} is 11357specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 11358this means that if a @code{Scalar_Storage_Order} attribute definition 11359clause is not confirming, then the type's @code{Bit_Order} shall be 11360specified explicitly and set to the same value. 11361 11362Derived types inherit an explicitly set scalar storage order from their parent 11363types. This may be overridden for the derived type by giving an explicit scalar 11364storage order for it. However, for a record extension, the derived type must 11365have the same scalar storage order as the parent type. 11366 11367A component of a record type that is itself a record or an array and that does 11368not start and end on a byte boundary must have have the same scalar storage 11369order as the record type. A component of a bit-packed array type that is itself 11370a record or an array must have the same scalar storage order as the array type. 11371 11372No component of a type that has an explicit @code{Scalar_Storage_Order} 11373attribute definition may be aliased. 11374 11375A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 11376with a value equal to @code{System.Default_Bit_Order}) has no effect. 11377 11378If the opposite storage order is specified, then whenever the value of 11379a scalar component of an object of type @code{S} is read, the storage 11380elements of the enclosing machine scalar are first reversed (before 11381retrieving the component value, possibly applying some shift and mask 11382operatings on the enclosing machine scalar), and the opposite operation 11383is done for writes. 11384 11385In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 11386are relaxed. Instead, the following rules apply: 11387 11388 11389@itemize * 11390 11391@item 11392the underlying storage elements are those at positions 11393@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 11394 11395@item 11396the sequence of underlying storage elements shall have 11397a size no greater than the largest machine scalar 11398 11399@item 11400the enclosing machine scalar is defined as the smallest machine 11401scalar starting at a position no greater than 11402@code{position + first_bit / storage_element_size} and covering 11403storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} 11404 11405@item 11406the position of the component is interpreted relative to that machine 11407scalar. 11408@end itemize 11409 11410If no scalar storage order is specified for a type (either directly, or by 11411inheritance in the case of a derived type), then the default is normally 11412the native ordering of the target, but this default can be overridden using 11413pragma @code{Default_Scalar_Storage_Order}. 11414 11415If a component of @code{T} is itself of a record or array type, the specfied 11416@code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit 11417attribute definition clause must be provided for the component type as well 11418if desired. 11419 11420Note that the scalar storage order only affects the in-memory data 11421representation. It has no effect on the representation used by stream 11422attributes. 11423 11424Note that debuggers may be unable to display the correct value of scalar 11425components of a type for which the opposite storage order is specified. 11426 11427@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 11428@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e9}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a0} 11429@section Attribute Simple_Storage_Pool 11430 11431 11432@geindex Storage pool 11433@geindex simple 11434 11435@geindex Simple storage pool 11436 11437@geindex Simple_Storage_Pool 11438 11439For every nonformal, nonderived access-to-object type @code{Acc}, the 11440representation attribute @code{Simple_Storage_Pool} may be specified 11441via an attribute_definition_clause (or by specifying the equivalent aspect): 11442 11443@example 11444My_Pool : My_Simple_Storage_Pool_Type; 11445 11446type Acc is access My_Data_Type; 11447 11448for Acc'Simple_Storage_Pool use My_Pool; 11449@end example 11450 11451The name given in an attribute_definition_clause for the 11452@code{Simple_Storage_Pool} attribute shall denote a variable of 11453a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}). 11454 11455The use of this attribute is only allowed for a prefix denoting a type 11456for which it has been specified. The type of the attribute is the type 11457of the variable specified as the simple storage pool of the access type, 11458and the attribute denotes that variable. 11459 11460It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 11461for the same access type. 11462 11463If the @code{Simple_Storage_Pool} attribute has been specified for an access 11464type, then applying the @code{Storage_Pool} attribute to the type is flagged 11465with a warning and its evaluation raises the exception @code{Program_Error}. 11466 11467If the Simple_Storage_Pool attribute has been specified for an access 11468type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} 11469returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 11470which is intended to indicate the number of storage elements reserved for 11471the simple storage pool. If the Storage_Size function has not been defined 11472for the simple storage pool type, then this attribute returns zero. 11473 11474If an access type @code{S} has a specified simple storage pool of type 11475@code{SSP}, then the evaluation of an allocator for that access type calls 11476the primitive @code{Allocate} procedure for type @code{SSP}, passing 11477@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 11478semantics of such allocators is the same as those defined for allocators 11479in section 13.11 of the @cite{Ada Reference Manual}, with the term 11480@emph{simple storage pool} substituted for @emph{storage pool}. 11481 11482If an access type @code{S} has a specified simple storage pool of type 11483@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 11484for that access type invokes the primitive @code{Deallocate} procedure 11485for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 11486parameter. The detailed semantics of such unchecked deallocations is the same 11487as defined in section 13.11.2 of the Ada Reference Manual, except that the 11488term @emph{simple storage pool} is substituted for @emph{storage pool}. 11489 11490@node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes 11491@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a1} 11492@section Attribute Small 11493 11494 11495@geindex Ada 83 attributes 11496 11497@geindex Small 11498 11499The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 11500fixed-point types. 11501GNAT also allows this attribute to be applied to floating-point types 11502for compatibility with Ada 83. See 11503the Ada 83 reference manual for an exact description of the semantics of 11504this attribute when applied to floating-point types. 11505 11506@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes 11507@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a2} 11508@section Attribute Storage_Unit 11509 11510 11511@geindex Storage_Unit 11512 11513@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 11514prefix) provides the same value as @code{System.Storage_Unit}. 11515 11516@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 11517@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a3} 11518@section Attribute Stub_Type 11519 11520 11521@geindex Stub_Type 11522 11523The GNAT implementation of remote access-to-classwide types is 11524organized as described in AARM section E.4 (20.t): a value of an RACW type 11525(designating a remote object) is represented as a normal access 11526value, pointing to a "stub" object which in turn contains the 11527necessary information to contact the designated remote object. A 11528call on any dispatching operation of such a stub object does the 11529remote call, if necessary, using the information in the stub object 11530to locate the target partition, etc. 11531 11532For a prefix @code{T} that denotes a remote access-to-classwide type, 11533@code{T'Stub_Type} denotes the type of the corresponding stub objects. 11534 11535By construction, the layout of @code{T'Stub_Type} is identical to that of 11536type @code{RACW_Stub_Type} declared in the internal implementation-defined 11537unit @code{System.Partition_Interface}. Use of this attribute will create 11538an implicit dependency on this unit. 11539 11540@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 11541@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a4} 11542@section Attribute System_Allocator_Alignment 11543 11544 11545@geindex Alignment 11546@geindex allocator 11547 11548@geindex System_Allocator_Alignment 11549 11550@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 11551permissible prefix) provides the observable guaranted to be honored by 11552the system allocator (malloc). This is a static value that can be used 11553in user storage pools based on malloc either to reject allocation 11554with alignment too large or to enable a realignment circuitry if the 11555alignment request is larger than this value. 11556 11557@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 11558@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a5} 11559@section Attribute Target_Name 11560 11561 11562@geindex Target_Name 11563 11564@code{Standard'Target_Name} (@code{Standard} is the only permissible 11565prefix) provides a static string value that identifies the target 11566for the current compilation. For GCC implementations, this is the 11567standard gcc target name without the terminating slash (for 11568example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 11569 11570@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 11571@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a6} 11572@section Attribute To_Address 11573 11574 11575@geindex To_Address 11576 11577The @code{System'To_Address} 11578(@code{System} is the only permissible prefix) 11579denotes a function identical to 11580@code{System.Storage_Elements.To_Address} except that 11581it is a static attribute. This means that if its argument is 11582a static expression, then the result of the attribute is a 11583static expression. This means that such an expression can be 11584used in contexts (e.g., preelaborable packages) which require a 11585static expression and where the function call could not be used 11586(since the function call is always nonstatic, even if its 11587argument is static). The argument must be in the range 11588-(2**(m-1)) .. 2**m-1, where m is the memory size 11589(typically 32 or 64). Negative values are intepreted in a 11590modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 11591a 32 bits machine). 11592 11593@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 11594@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a7} 11595@section Attribute To_Any 11596 11597 11598@geindex To_Any 11599 11600This internal attribute is used for the generation of remote subprogram 11601stubs in the context of the Distributed Systems Annex. 11602 11603@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 11604@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a8} 11605@section Attribute Type_Class 11606 11607 11608@geindex Type_Class 11609 11610@code{typ'Type_Class} for any type or subtype @cite{typ} yields 11611the value of the type class for the full type of @cite{typ}. If 11612@cite{typ} is a generic formal type, the value is the value for the 11613corresponding actual subtype. The value of this attribute is of type 11614@code{System.Aux_DEC.Type_Class}, which has the following definition: 11615 11616@example 11617type Type_Class is 11618 (Type_Class_Enumeration, 11619 Type_Class_Integer, 11620 Type_Class_Fixed_Point, 11621 Type_Class_Floating_Point, 11622 Type_Class_Array, 11623 Type_Class_Record, 11624 Type_Class_Access, 11625 Type_Class_Task, 11626 Type_Class_Address); 11627@end example 11628 11629Protected types yield the value @code{Type_Class_Task}, which thus 11630applies to all concurrent types. This attribute is designed to 11631be compatible with the DEC Ada 83 attribute of the same name. 11632 11633@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 11634@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a9} 11635@section Attribute Type_Key 11636 11637 11638@geindex Type_Key 11639 11640The @code{Type_Key} attribute is applicable to a type or subtype and 11641yields a value of type Standard.String containing encoded information 11642about the type or subtype. This provides improved compatibility with 11643other implementations that support this attribute. 11644 11645@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 11646@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1aa} 11647@section Attribute TypeCode 11648 11649 11650@geindex TypeCode 11651 11652This internal attribute is used for the generation of remote subprogram 11653stubs in the context of the Distributed Systems Annex. 11654 11655@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 11656@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ab} 11657@section Attribute Unconstrained_Array 11658 11659 11660@geindex Unconstrained_Array 11661 11662The @code{Unconstrained_Array} attribute can be used with a prefix that 11663denotes any type or subtype. It is a static attribute that yields 11664@code{True} if the prefix designates an unconstrained array, 11665and @code{False} otherwise. In a generic instance, the result is 11666still static, and yields the result of applying this test to the 11667generic actual. 11668 11669@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 11670@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ac} 11671@section Attribute Universal_Literal_String 11672 11673 11674@geindex Named numbers 11675@geindex representation of 11676 11677@geindex Universal_Literal_String 11678 11679The prefix of @code{Universal_Literal_String} must be a named 11680number. The static result is the string consisting of the characters of 11681the number as defined in the original source. This allows the user 11682program to access the actual text of named numbers without intermediate 11683conversions and without the need to enclose the strings in quotes (which 11684would preclude their use as numbers). 11685 11686For example, the following program prints the first 50 digits of pi: 11687 11688@example 11689with Text_IO; use Text_IO; 11690with Ada.Numerics; 11691procedure Pi is 11692begin 11693 Put (Ada.Numerics.Pi'Universal_Literal_String); 11694end; 11695@end example 11696 11697@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 11698@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ad} 11699@section Attribute Unrestricted_Access 11700 11701 11702@geindex Access 11703@geindex unrestricted 11704 11705@geindex Unrestricted_Access 11706 11707The @code{Unrestricted_Access} attribute is similar to @code{Access} 11708except that all accessibility and aliased view checks are omitted. This 11709is a user-beware attribute. 11710 11711For objects, it is similar to @code{Address}, for which it is a 11712desirable replacement where the value desired is an access type. 11713In other words, its effect is similar to first applying the 11714@code{Address} attribute and then doing an unchecked conversion to a 11715desired access type. 11716 11717For subprograms, @code{P'Unrestricted_Access} may be used where 11718@code{P'Access} would be illegal, to construct a value of a 11719less-nested named access type that designates a more-nested 11720subprogram. This value may be used in indirect calls, so long as the 11721more-nested subprogram still exists; once the subprogram containing it 11722has returned, such calls are erroneous. For example: 11723 11724@example 11725package body P is 11726 11727 type Less_Nested is not null access procedure; 11728 Global : Less_Nested; 11729 11730 procedure P1 is 11731 begin 11732 Global.all; 11733 end P1; 11734 11735 procedure P2 is 11736 Local_Var : Integer; 11737 11738 procedure More_Nested is 11739 begin 11740 ... Local_Var ... 11741 end More_Nested; 11742 begin 11743 Global := More_Nested'Unrestricted_Access; 11744 P1; 11745 end P2; 11746 11747end P; 11748@end example 11749 11750When P1 is called from P2, the call via Global is OK, but if P1 were 11751called after P2 returns, it would be an erroneous use of a dangling 11752pointer. 11753 11754For objects, it is possible to use @code{Unrestricted_Access} for any 11755type. However, if the result is of an access-to-unconstrained array 11756subtype, then the resulting pointer has the same scope as the context 11757of the attribute, and must not be returned to some enclosing scope. 11758For instance, if a function uses @code{Unrestricted_Access} to create 11759an access-to-unconstrained-array and returns that value to the caller, 11760the result will involve dangling pointers. In addition, it is only 11761valid to create pointers to unconstrained arrays using this attribute 11762if the pointer has the normal default 'fat' representation where a 11763pointer has two components, one points to the array and one points to 11764the bounds. If a size clause is used to force 'thin' representation 11765for a pointer to unconstrained where there is only space for a single 11766pointer, then the resulting pointer is not usable. 11767 11768In the simple case where a direct use of Unrestricted_Access attempts 11769to make a thin pointer for a non-aliased object, the compiler will 11770reject the use as illegal, as shown in the following example: 11771 11772@example 11773with System; use System; 11774procedure SliceUA2 is 11775 type A is access all String; 11776 for A'Size use Standard'Address_Size; 11777 11778 procedure P (Arg : A) is 11779 begin 11780 null; 11781 end P; 11782 11783 X : String := "hello world!"; 11784 X2 : aliased String := "hello world!"; 11785 11786 AV : A := X'Unrestricted_Access; -- ERROR 11787 | 11788>>> illegal use of Unrestricted_Access attribute 11789>>> attempt to generate thin pointer to unaliased object 11790 11791begin 11792 P (X'Unrestricted_Access); -- ERROR 11793 | 11794>>> illegal use of Unrestricted_Access attribute 11795>>> attempt to generate thin pointer to unaliased object 11796 11797 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11798 | 11799>>> illegal use of Unrestricted_Access attribute 11800>>> attempt to generate thin pointer to unaliased object 11801 11802 P (X2'Unrestricted_Access); -- OK 11803end; 11804@end example 11805 11806but other cases cannot be detected by the compiler, and are 11807considered to be erroneous. Consider the following example: 11808 11809@example 11810with System; use System; 11811with System; use System; 11812procedure SliceUA is 11813 type AF is access all String; 11814 11815 type A is access all String; 11816 for A'Size use Standard'Address_Size; 11817 11818 procedure P (Arg : A) is 11819 begin 11820 if Arg'Length /= 6 then 11821 raise Program_Error; 11822 end if; 11823 end P; 11824 11825 X : String := "hello world!"; 11826 Y : AF := X (7 .. 12)'Unrestricted_Access; 11827 11828begin 11829 P (A (Y)); 11830end; 11831@end example 11832 11833A normal unconstrained array value 11834or a constrained array object marked as aliased has the bounds in memory 11835just before the array, so a thin pointer can retrieve both the data and 11836the bounds. But in this case, the non-aliased object @code{X} does not have the 11837bounds before the string. If the size clause for type @code{A} 11838were not present, then the pointer 11839would be a fat pointer, where one component is a pointer to the bounds, 11840and all would be well. But with the size clause present, the conversion from 11841fat pointer to thin pointer in the call loses the bounds, and so this 11842is erroneous, and the program likely raises a @code{Program_Error} exception. 11843 11844In general, it is advisable to completely 11845avoid mixing the use of thin pointers and the use of 11846@code{Unrestricted_Access} where the designated type is an 11847unconstrained array. The use of thin pointers should be restricted to 11848cases of porting legacy code that implicitly assumes the size of pointers, 11849and such code should not in any case be using this attribute. 11850 11851Another erroneous situation arises if the attribute is 11852applied to a constant. The resulting pointer can be used to access the 11853constant, but the effect of trying to modify a constant in this manner 11854is not well-defined. Consider this example: 11855 11856@example 11857P : constant Integer := 4; 11858type R is access all Integer; 11859RV : R := P'Unrestricted_Access; 11860.. 11861RV.all := 3; 11862@end example 11863 11864Here we attempt to modify the constant P from 4 to 3, but the compiler may 11865or may not notice this attempt, and subsequent references to P may yield 11866either the value 3 or the value 4 or the assignment may blow up if the 11867compiler decides to put P in read-only memory. One particular case where 11868@code{Unrestricted_Access} can be used in this way is to modify the 11869value of an @code{in} parameter: 11870 11871@example 11872procedure K (S : in String) is 11873 type R is access all Character; 11874 RV : R := S (3)'Unrestricted_Access; 11875begin 11876 RV.all := 'a'; 11877end; 11878@end example 11879 11880In general this is a risky approach. It may appear to "work" but such uses of 11881@code{Unrestricted_Access} are potentially non-portable, even from one version 11882of GNAT to another, so are best avoided if possible. 11883 11884@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes 11885@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ae} 11886@section Attribute Update 11887 11888 11889@geindex Update 11890 11891The @code{Update} attribute creates a copy of an array or record value 11892with one or more modified components. The syntax is: 11893 11894@example 11895PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 11896PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 11897PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 11898 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 11899 11900MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 11901INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 11902INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 11903@end example 11904 11905where @code{PREFIX} is the name of an array or record object, the 11906association list in parentheses does not contain an @code{others} 11907choice and the box symbol @code{<>} may not appear in any 11908expression. The effect is to yield a copy of the array or record value 11909which is unchanged apart from the components mentioned in the 11910association list, which are changed to the indicated value. The 11911original value of the array or record value is not affected. For 11912example: 11913 11914@example 11915type Arr is Array (1 .. 5) of Integer; 11916... 11917Avar1 : Arr := (1,2,3,4,5); 11918Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 11919@end example 11920 11921yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 11922begin unmodified. Similarly: 11923 11924@example 11925type Rec is A, B, C : Integer; 11926... 11927Rvar1 : Rec := (A => 1, B => 2, C => 3); 11928Rvar2 : Rec := Rvar1'Update (B => 20); 11929@end example 11930 11931yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 11932with @code{Rvar1} being unmodifed. 11933Note that the value of the attribute reference is computed 11934completely before it is used. This means that if you write: 11935 11936@example 11937Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 11938@end example 11939 11940then the value of @code{Avar1} is not modified if @code{Function_Call} 11941raises an exception, unlike the effect of a series of direct assignments 11942to elements of @code{Avar1}. In general this requires that 11943two extra complete copies of the object are required, which should be 11944kept in mind when considering efficiency. 11945 11946The @code{Update} attribute cannot be applied to prefixes of a limited 11947type, and cannot reference discriminants in the case of a record type. 11948The accessibility level of an Update attribute result object is defined 11949as for an aggregate. 11950 11951In the record case, no component can be mentioned more than once. In 11952the array case, two overlapping ranges can appear in the association list, 11953in which case the modifications are processed left to right. 11954 11955Multi-dimensional arrays can be modified, as shown by this example: 11956 11957@example 11958A : array (1 .. 10, 1 .. 10) of Integer; 11959.. 11960A := A'Update ((1, 2) => 20, (3, 4) => 30); 11961@end example 11962 11963which changes element (1,2) to 20 and (3,4) to 30. 11964 11965@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes 11966@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1af} 11967@section Attribute Valid_Scalars 11968 11969 11970@geindex Valid_Scalars 11971 11972The @code{'Valid_Scalars} attribute is intended to make it easier to check the 11973validity of scalar subcomponents of composite objects. The attribute is defined 11974for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type 11975except for tagged private or @code{Unchecked_Union} types. The value of the 11976attribute is of type @code{Boolean}. 11977 11978@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of 11979@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if 11980@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent 11981to attribute @code{'Valid} for scalar types. 11982 11983It is not specified in what order the subcomponents are checked, nor whether 11984any more are checked after any one of them is determined to be invalid. If the 11985prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated 11986specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then 11987only the subcomponents of @code{T} are checked; in other words, components of 11988extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. 11989 11990The compiler will issue a warning if it can be determined at compile time that 11991the prefix of the attribute has no scalar subcomponents. 11992 11993Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of 11994a large variant record. If the attribute is called in many places in the same 11995program applied to objects of the same type, it can reduce program size to 11996write a function with a single use of the attribute, and then call that 11997function from multiple places. 11998 11999@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 12000@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b0} 12001@section Attribute VADS_Size 12002 12003 12004@geindex Size 12005@geindex VADS compatibility 12006 12007@geindex VADS_Size 12008 12009The @code{'VADS_Size} attribute is intended to make it easier to port 12010legacy code which relies on the semantics of @code{'Size} as implemented 12011by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 12012same semantic interpretation. In particular, @code{'VADS_Size} applied 12013to a predefined or other primitive type with no Size clause yields the 12014Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 12015typical machines). In addition @code{'VADS_Size} applied to an object 12016gives the result that would be obtained by applying the attribute to 12017the corresponding type. 12018 12019@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 12020@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b1}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{163} 12021@section Attribute Value_Size 12022 12023 12024@geindex Size 12025@geindex setting for not-first subtype 12026 12027@geindex Value_Size 12028 12029@code{type'Value_Size} is the number of bits required to represent 12030a value of the given subtype. It is the same as @code{type'Size}, 12031but, unlike @code{Size}, may be set for non-first subtypes. 12032 12033@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 12034@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b2} 12035@section Attribute Wchar_T_Size 12036 12037 12038@geindex Wchar_T_Size 12039 12040@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 12041prefix) provides the size in bits of the C @code{wchar_t} type 12042primarily for constructing the definition of this type in 12043package @code{Interfaces.C}. The result is a static constant. 12044 12045@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 12046@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b3} 12047@section Attribute Word_Size 12048 12049 12050@geindex Word_Size 12051 12052@code{Standard'Word_Size} (@code{Standard} is the only permissible 12053prefix) provides the value @code{System.Word_Size}. The result is 12054a static constant. 12055 12056@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 12057@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{1b4}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b5} 12058@chapter Standard and Implementation Defined Restrictions 12059 12060 12061All Ada Reference Manual-defined Restriction identifiers are implemented: 12062 12063 12064@itemize * 12065 12066@item 12067language-defined restrictions (see 13.12.1) 12068 12069@item 12070tasking restrictions (see D.7) 12071 12072@item 12073high integrity restrictions (see H.4) 12074@end itemize 12075 12076GNAT implements additional restriction identifiers. All restrictions, whether 12077language defined or GNAT-specific, are listed in the following. 12078 12079@menu 12080* Partition-Wide Restrictions:: 12081* Program Unit Level Restrictions:: 12082 12083@end menu 12084 12085@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 12086@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b6}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b7} 12087@section Partition-Wide Restrictions 12088 12089 12090There are two separate lists of restriction identifiers. The first 12091set requires consistency throughout a partition (in other words, if the 12092restriction identifier is used for any compilation unit in the partition, 12093then all compilation units in the partition must obey the restriction). 12094 12095@menu 12096* Immediate_Reclamation:: 12097* Max_Asynchronous_Select_Nesting:: 12098* Max_Entry_Queue_Length:: 12099* Max_Protected_Entries:: 12100* Max_Select_Alternatives:: 12101* Max_Storage_At_Blocking:: 12102* Max_Task_Entries:: 12103* Max_Tasks:: 12104* No_Abort_Statements:: 12105* No_Access_Parameter_Allocators:: 12106* No_Access_Subprograms:: 12107* No_Allocators:: 12108* No_Anonymous_Allocators:: 12109* No_Asynchronous_Control:: 12110* No_Calendar:: 12111* No_Coextensions:: 12112* No_Default_Initialization:: 12113* No_Delay:: 12114* No_Dependence:: 12115* No_Direct_Boolean_Operators:: 12116* No_Dispatch:: 12117* No_Dispatching_Calls:: 12118* No_Dynamic_Attachment:: 12119* No_Dynamic_Priorities:: 12120* No_Entry_Calls_In_Elaboration_Code:: 12121* No_Enumeration_Maps:: 12122* No_Exception_Handlers:: 12123* No_Exception_Propagation:: 12124* No_Exception_Registration:: 12125* No_Exceptions:: 12126* No_Finalization:: 12127* No_Fixed_Point:: 12128* No_Floating_Point:: 12129* No_Implicit_Conditionals:: 12130* No_Implicit_Dynamic_Code:: 12131* No_Implicit_Heap_Allocations:: 12132* No_Implicit_Protected_Object_Allocations:: 12133* No_Implicit_Task_Allocations:: 12134* No_Initialize_Scalars:: 12135* No_IO:: 12136* No_Local_Allocators:: 12137* No_Local_Protected_Objects:: 12138* No_Local_Timing_Events:: 12139* No_Long_Long_Integers:: 12140* No_Multiple_Elaboration:: 12141* No_Nested_Finalization:: 12142* No_Protected_Type_Allocators:: 12143* No_Protected_Types:: 12144* No_Recursion:: 12145* No_Reentrancy:: 12146* No_Relative_Delay:: 12147* No_Requeue_Statements:: 12148* No_Secondary_Stack:: 12149* No_Select_Statements:: 12150* No_Specific_Termination_Handlers:: 12151* No_Specification_of_Aspect:: 12152* No_Standard_Allocators_After_Elaboration:: 12153* No_Standard_Storage_Pools:: 12154* No_Stream_Optimizations:: 12155* No_Streams:: 12156* No_Task_Allocators:: 12157* No_Task_At_Interrupt_Priority:: 12158* No_Task_Attributes_Package:: 12159* No_Task_Hierarchy:: 12160* No_Task_Termination:: 12161* No_Tasking:: 12162* No_Terminate_Alternatives:: 12163* No_Unchecked_Access:: 12164* No_Unchecked_Conversion:: 12165* No_Unchecked_Deallocation:: 12166* No_Use_Of_Entity:: 12167* Pure_Barriers:: 12168* Simple_Barriers:: 12169* Static_Priorities:: 12170* Static_Storage_Size:: 12171 12172@end menu 12173 12174@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 12175@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b8} 12176@subsection Immediate_Reclamation 12177 12178 12179@geindex Immediate_Reclamation 12180 12181[RM H.4] This restriction ensures that, except for storage occupied by 12182objects created by allocators and not deallocated via unchecked 12183deallocation, any storage reserved at run time for an object is 12184immediately reclaimed when the object no longer exists. 12185 12186@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 12187@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b9} 12188@subsection Max_Asynchronous_Select_Nesting 12189 12190 12191@geindex Max_Asynchronous_Select_Nesting 12192 12193[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 12194selects. Violations of this restriction with a value of zero are 12195detected at compile time. Violations of this restriction with values 12196other than zero cause Storage_Error to be raised. 12197 12198@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 12199@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1ba} 12200@subsection Max_Entry_Queue_Length 12201 12202 12203@geindex Max_Entry_Queue_Length 12204 12205[RM D.7] This restriction is a declaration that any protected entry compiled in 12206the scope of the restriction has at most the specified number of 12207tasks waiting on the entry at any one time, and so no queue is required. 12208Note that this restriction is checked at run time. Violation of this 12209restriction results in the raising of Program_Error exception at the point of 12210the call. 12211 12212@geindex Max_Entry_Queue_Depth 12213 12214The restriction @code{Max_Entry_Queue_Depth} is recognized as a 12215synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 12216compatibility purposes (and a warning will be generated for its use if 12217warnings on obsolescent features are activated). 12218 12219@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 12220@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bb} 12221@subsection Max_Protected_Entries 12222 12223 12224@geindex Max_Protected_Entries 12225 12226[RM D.7] Specifies the maximum number of entries per protected type. The 12227bounds of every entry family of a protected unit shall be static, or shall be 12228defined by a discriminant of a subtype whose corresponding bound is static. 12229 12230@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 12231@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bc} 12232@subsection Max_Select_Alternatives 12233 12234 12235@geindex Max_Select_Alternatives 12236 12237[RM D.7] Specifies the maximum number of alternatives in a selective accept. 12238 12239@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 12240@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1bd} 12241@subsection Max_Storage_At_Blocking 12242 12243 12244@geindex Max_Storage_At_Blocking 12245 12246[RM D.7] Specifies the maximum portion (in storage elements) of a task's 12247Storage_Size that can be retained by a blocked task. A violation of this 12248restriction causes Storage_Error to be raised. 12249 12250@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 12251@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1be} 12252@subsection Max_Task_Entries 12253 12254 12255@geindex Max_Task_Entries 12256 12257[RM D.7] Specifies the maximum number of entries 12258per task. The bounds of every entry family 12259of a task unit shall be static, or shall be 12260defined by a discriminant of a subtype whose 12261corresponding bound is static. 12262 12263@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 12264@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1bf} 12265@subsection Max_Tasks 12266 12267 12268@geindex Max_Tasks 12269 12270[RM D.7] Specifies the maximum number of task that may be created, not 12271counting the creation of the environment task. Violations of this 12272restriction with a value of zero are detected at compile 12273time. Violations of this restriction with values other than zero cause 12274Storage_Error to be raised. 12275 12276@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 12277@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c0} 12278@subsection No_Abort_Statements 12279 12280 12281@geindex No_Abort_Statements 12282 12283[RM D.7] There are no abort_statements, and there are 12284no calls to Task_Identification.Abort_Task. 12285 12286@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 12287@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c1} 12288@subsection No_Access_Parameter_Allocators 12289 12290 12291@geindex No_Access_Parameter_Allocators 12292 12293[RM H.4] This restriction ensures at compile time that there are no 12294occurrences of an allocator as the actual parameter to an access 12295parameter. 12296 12297@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 12298@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c2} 12299@subsection No_Access_Subprograms 12300 12301 12302@geindex No_Access_Subprograms 12303 12304[RM H.4] This restriction ensures at compile time that there are no 12305declarations of access-to-subprogram types. 12306 12307@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 12308@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c3} 12309@subsection No_Allocators 12310 12311 12312@geindex No_Allocators 12313 12314[RM H.4] This restriction ensures at compile time that there are no 12315occurrences of an allocator. 12316 12317@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 12318@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c4} 12319@subsection No_Anonymous_Allocators 12320 12321 12322@geindex No_Anonymous_Allocators 12323 12324[RM H.4] This restriction ensures at compile time that there are no 12325occurrences of an allocator of anonymous access type. 12326 12327@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 12328@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c5} 12329@subsection No_Asynchronous_Control 12330 12331 12332@geindex No_Asynchronous_Control 12333 12334[RM J.13] This restriction ensures at compile time that there are no semantic 12335dependences on the predefined package Asynchronous_Task_Control. 12336 12337@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 12338@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c6} 12339@subsection No_Calendar 12340 12341 12342@geindex No_Calendar 12343 12344[GNAT] This restriction ensures at compile time that there are no semantic 12345dependences on package Calendar. 12346 12347@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 12348@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c7} 12349@subsection No_Coextensions 12350 12351 12352@geindex No_Coextensions 12353 12354[RM H.4] This restriction ensures at compile time that there are no 12355coextensions. See 3.10.2. 12356 12357@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 12358@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c8} 12359@subsection No_Default_Initialization 12360 12361 12362@geindex No_Default_Initialization 12363 12364[GNAT] This restriction prohibits any instance of default initialization 12365of variables. The binder implements a consistency rule which prevents 12366any unit compiled without the restriction from with'ing a unit with the 12367restriction (this allows the generation of initialization procedures to 12368be skipped, since you can be sure that no call is ever generated to an 12369initialization procedure in a unit with the restriction active). If used 12370in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 12371is to prohibit all cases of variables declared without a specific 12372initializer (including the case of OUT scalar parameters). 12373 12374@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 12375@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c9} 12376@subsection No_Delay 12377 12378 12379@geindex No_Delay 12380 12381[RM H.4] This restriction ensures at compile time that there are no 12382delay statements and no semantic dependences on package Calendar. 12383 12384@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 12385@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1ca} 12386@subsection No_Dependence 12387 12388 12389@geindex No_Dependence 12390 12391[RM 13.12.1] This restriction ensures at compile time that there are no 12392dependences on a library unit. 12393 12394@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 12395@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cb} 12396@subsection No_Direct_Boolean_Operators 12397 12398 12399@geindex No_Direct_Boolean_Operators 12400 12401[GNAT] This restriction ensures that no logical operators (and/or/xor) 12402are used on operands of type Boolean (or any type derived from Boolean). 12403This is intended for use in safety critical programs where the certification 12404protocol requires the use of short-circuit (and then, or else) forms for all 12405composite boolean operations. 12406 12407@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 12408@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cc} 12409@subsection No_Dispatch 12410 12411 12412@geindex No_Dispatch 12413 12414[RM H.4] This restriction ensures at compile time that there are no 12415occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 12416 12417@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 12418@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1cd} 12419@subsection No_Dispatching_Calls 12420 12421 12422@geindex No_Dispatching_Calls 12423 12424[GNAT] This restriction ensures at compile time that the code generated by the 12425compiler involves no dispatching calls. The use of this restriction allows the 12426safe use of record extensions, classwide membership tests and other classwide 12427features not involving implicit dispatching. This restriction ensures that 12428the code contains no indirect calls through a dispatching mechanism. Note that 12429this includes internally-generated calls created by the compiler, for example 12430in the implementation of class-wide objects assignments. The 12431membership test is allowed in the presence of this restriction, because its 12432implementation requires no dispatching. 12433This restriction is comparable to the official Ada restriction 12434@code{No_Dispatch} except that it is a bit less restrictive in that it allows 12435all classwide constructs that do not imply dispatching. 12436The following example indicates constructs that violate this restriction. 12437 12438@example 12439package Pkg is 12440 type T is tagged record 12441 Data : Natural; 12442 end record; 12443 procedure P (X : T); 12444 12445 type DT is new T with record 12446 More_Data : Natural; 12447 end record; 12448 procedure Q (X : DT); 12449end Pkg; 12450 12451with Pkg; use Pkg; 12452procedure Example is 12453 procedure Test (O : T'Class) is 12454 N : Natural := O'Size;-- Error: Dispatching call 12455 C : T'Class := O; -- Error: implicit Dispatching Call 12456 begin 12457 if O in DT'Class then -- OK : Membership test 12458 Q (DT (O)); -- OK : Type conversion plus direct call 12459 else 12460 P (O); -- Error: Dispatching call 12461 end if; 12462 end Test; 12463 12464 Obj : DT; 12465begin 12466 P (Obj); -- OK : Direct call 12467 P (T (Obj)); -- OK : Type conversion plus direct call 12468 P (T'Class (Obj)); -- Error: Dispatching call 12469 12470 Test (Obj); -- OK : Type conversion 12471 12472 if Obj in T'Class then -- OK : Membership test 12473 null; 12474 end if; 12475end Example; 12476@end example 12477 12478@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 12479@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1ce} 12480@subsection No_Dynamic_Attachment 12481 12482 12483@geindex No_Dynamic_Attachment 12484 12485[RM D.7] This restriction ensures that there is no call to any of the 12486operations defined in package Ada.Interrupts 12487(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 12488Detach_Handler, and Reference). 12489 12490@geindex No_Dynamic_Interrupts 12491 12492The restriction @code{No_Dynamic_Interrupts} is recognized as a 12493synonym for @code{No_Dynamic_Attachment}. This is retained for historical 12494compatibility purposes (and a warning will be generated for its use if 12495warnings on obsolescent features are activated). 12496 12497@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 12498@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1cf} 12499@subsection No_Dynamic_Priorities 12500 12501 12502@geindex No_Dynamic_Priorities 12503 12504[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 12505 12506@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 12507@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d0} 12508@subsection No_Entry_Calls_In_Elaboration_Code 12509 12510 12511@geindex No_Entry_Calls_In_Elaboration_Code 12512 12513[GNAT] This restriction ensures at compile time that no task or protected entry 12514calls are made during elaboration code. As a result of the use of this 12515restriction, the compiler can assume that no code past an accept statement 12516in a task can be executed at elaboration time. 12517 12518@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 12519@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d1} 12520@subsection No_Enumeration_Maps 12521 12522 12523@geindex No_Enumeration_Maps 12524 12525[GNAT] This restriction ensures at compile time that no operations requiring 12526enumeration maps are used (that is Image and Value attributes applied 12527to enumeration types). 12528 12529@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 12530@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d2} 12531@subsection No_Exception_Handlers 12532 12533 12534@geindex No_Exception_Handlers 12535 12536[GNAT] This restriction ensures at compile time that there are no explicit 12537exception handlers. It also indicates that no exception propagation will 12538be provided. In this mode, exceptions may be raised but will result in 12539an immediate call to the last chance handler, a routine that the user 12540must define with the following profile: 12541 12542@example 12543procedure Last_Chance_Handler 12544 (Source_Location : System.Address; Line : Integer); 12545pragma Export (C, Last_Chance_Handler, 12546 "__gnat_last_chance_handler"); 12547@end example 12548 12549The parameter is a C null-terminated string representing a message to be 12550associated with the exception (typically the source location of the raise 12551statement generated by the compiler). The Line parameter when nonzero 12552represents the line number in the source program where the raise occurs. 12553 12554@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 12555@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d3} 12556@subsection No_Exception_Propagation 12557 12558 12559@geindex No_Exception_Propagation 12560 12561[GNAT] This restriction guarantees that exceptions are never propagated 12562to an outer subprogram scope. The only case in which an exception may 12563be raised is when the handler is statically in the same subprogram, so 12564that the effect of a raise is essentially like a goto statement. Any 12565other raise statement (implicit or explicit) will be considered 12566unhandled. Exception handlers are allowed, but may not contain an 12567exception occurrence identifier (exception choice). In addition, use of 12568the package GNAT.Current_Exception is not permitted, and reraise 12569statements (raise with no operand) are not permitted. 12570 12571@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 12572@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d4} 12573@subsection No_Exception_Registration 12574 12575 12576@geindex No_Exception_Registration 12577 12578[GNAT] This restriction ensures at compile time that no stream operations for 12579types Exception_Id or Exception_Occurrence are used. This also makes it 12580impossible to pass exceptions to or from a partition with this restriction 12581in a distributed environment. If this restriction is active, the generated 12582code is simplified by omitting the otherwise-required global registration 12583of exceptions when they are declared. 12584 12585@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 12586@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d5} 12587@subsection No_Exceptions 12588 12589 12590@geindex No_Exceptions 12591 12592[RM H.4] This restriction ensures at compile time that there are no 12593raise statements and no exception handlers and also suppresses the 12594generation of language-defined run-time checks. 12595 12596@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 12597@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d6} 12598@subsection No_Finalization 12599 12600 12601@geindex No_Finalization 12602 12603[GNAT] This restriction disables the language features described in 12604chapter 7.6 of the Ada 2005 RM as well as all form of code generation 12605performed by the compiler to support these features. The following types 12606are no longer considered controlled when this restriction is in effect: 12607 12608 12609@itemize * 12610 12611@item 12612@code{Ada.Finalization.Controlled} 12613 12614@item 12615@code{Ada.Finalization.Limited_Controlled} 12616 12617@item 12618Derivations from @code{Controlled} or @code{Limited_Controlled} 12619 12620@item 12621Class-wide types 12622 12623@item 12624Protected types 12625 12626@item 12627Task types 12628 12629@item 12630Array and record types with controlled components 12631@end itemize 12632 12633The compiler no longer generates code to initialize, finalize or adjust an 12634object or a nested component, either declared on the stack or on the heap. The 12635deallocation of a controlled object no longer finalizes its contents. 12636 12637@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 12638@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d7} 12639@subsection No_Fixed_Point 12640 12641 12642@geindex No_Fixed_Point 12643 12644[RM H.4] This restriction ensures at compile time that there are no 12645occurrences of fixed point types and operations. 12646 12647@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 12648@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d8} 12649@subsection No_Floating_Point 12650 12651 12652@geindex No_Floating_Point 12653 12654[RM H.4] This restriction ensures at compile time that there are no 12655occurrences of floating point types and operations. 12656 12657@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 12658@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d9} 12659@subsection No_Implicit_Conditionals 12660 12661 12662@geindex No_Implicit_Conditionals 12663 12664[GNAT] This restriction ensures that the generated code does not contain any 12665implicit conditionals, either by modifying the generated code where possible, 12666or by rejecting any construct that would otherwise generate an implicit 12667conditional. Note that this check does not include run time constraint 12668checks, which on some targets may generate implicit conditionals as 12669well. To control the latter, constraint checks can be suppressed in the 12670normal manner. Constructs generating implicit conditionals include comparisons 12671of composite objects and the Max/Min attributes. 12672 12673@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 12674@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1da} 12675@subsection No_Implicit_Dynamic_Code 12676 12677 12678@geindex No_Implicit_Dynamic_Code 12679 12680@geindex trampoline 12681 12682[GNAT] This restriction prevents the compiler from building 'trampolines'. 12683This is a structure that is built on the stack and contains dynamic 12684code to be executed at run time. On some targets, a trampoline is 12685built for the following features: @code{Access}, 12686@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 12687nested task bodies; primitive operations of nested tagged types. 12688Trampolines do not work on machines that prevent execution of stack 12689data. For example, on windows systems, enabling DEP (data execution 12690protection) will cause trampolines to raise an exception. 12691Trampolines are also quite slow at run time. 12692 12693On many targets, trampolines have been largely eliminated. Look at the 12694version of system.ads for your target --- if it has 12695Always_Compatible_Rep equal to False, then trampolines are largely 12696eliminated. In particular, a trampoline is built for the following 12697features: @code{Address} of a nested subprogram; 12698@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 12699but only if pragma Favor_Top_Level applies, or the access type has a 12700foreign-language convention; primitive operations of nested tagged 12701types. 12702 12703@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 12704@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1db} 12705@subsection No_Implicit_Heap_Allocations 12706 12707 12708@geindex No_Implicit_Heap_Allocations 12709 12710[RM D.7] No constructs are allowed to cause implicit heap allocation. 12711 12712@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12713@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1dc} 12714@subsection No_Implicit_Protected_Object_Allocations 12715 12716 12717@geindex No_Implicit_Protected_Object_Allocations 12718 12719[GNAT] No constructs are allowed to cause implicit heap allocation of a 12720protected object. 12721 12722@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12723@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1dd} 12724@subsection No_Implicit_Task_Allocations 12725 12726 12727@geindex No_Implicit_Task_Allocations 12728 12729[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12730 12731@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12732@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1de} 12733@subsection No_Initialize_Scalars 12734 12735 12736@geindex No_Initialize_Scalars 12737 12738[GNAT] This restriction ensures that no unit in the partition is compiled with 12739pragma Initialize_Scalars. This allows the generation of more efficient 12740code, and in particular eliminates dummy null initialization routines that 12741are otherwise generated for some record and array types. 12742 12743@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12744@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1df} 12745@subsection No_IO 12746 12747 12748@geindex No_IO 12749 12750[RM H.4] This restriction ensures at compile time that there are no 12751dependences on any of the library units Sequential_IO, Direct_IO, 12752Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12753 12754@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12755@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e0} 12756@subsection No_Local_Allocators 12757 12758 12759@geindex No_Local_Allocators 12760 12761[RM H.4] This restriction ensures at compile time that there are no 12762occurrences of an allocator in subprograms, generic subprograms, tasks, 12763and entry bodies. 12764 12765@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12766@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e1} 12767@subsection No_Local_Protected_Objects 12768 12769 12770@geindex No_Local_Protected_Objects 12771 12772[RM D.7] This restriction ensures at compile time that protected objects are 12773only declared at the library level. 12774 12775@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12776@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e2} 12777@subsection No_Local_Timing_Events 12778 12779 12780@geindex No_Local_Timing_Events 12781 12782[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 12783declared at the library level. 12784 12785@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12786@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e3} 12787@subsection No_Long_Long_Integers 12788 12789 12790@geindex No_Long_Long_Integers 12791 12792[GNAT] This partition-wide restriction forbids any explicit reference to 12793type Standard.Long_Long_Integer, and also forbids declaring range types whose 12794implicit base type is Long_Long_Integer, and modular types whose size exceeds 12795Long_Integer'Size. 12796 12797@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12798@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e4} 12799@subsection No_Multiple_Elaboration 12800 12801 12802@geindex No_Multiple_Elaboration 12803 12804[GNAT] When this restriction is active and the static elaboration model is 12805used, and -fpreserve-control-flow is not used, the compiler is allowed to 12806suppress the elaboration counter normally associated with the unit, even if 12807the unit has elaboration code. This counter is typically used to check for 12808access before elaboration and to control multiple elaboration attempts. If the 12809restriction is used, then the situations in which multiple elaboration is 12810possible, including non-Ada main programs and Stand Alone libraries, are not 12811permitted and will be diagnosed by the binder. 12812 12813@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12814@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e5} 12815@subsection No_Nested_Finalization 12816 12817 12818@geindex No_Nested_Finalization 12819 12820[RM D.7] All objects requiring finalization are declared at the library level. 12821 12822@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12823@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e6} 12824@subsection No_Protected_Type_Allocators 12825 12826 12827@geindex No_Protected_Type_Allocators 12828 12829[RM D.7] This restriction ensures at compile time that there are no allocator 12830expressions that attempt to allocate protected objects. 12831 12832@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 12833@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e7} 12834@subsection No_Protected_Types 12835 12836 12837@geindex No_Protected_Types 12838 12839[RM H.4] This restriction ensures at compile time that there are no 12840declarations of protected types or protected objects. 12841 12842@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 12843@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e8} 12844@subsection No_Recursion 12845 12846 12847@geindex No_Recursion 12848 12849[RM H.4] A program execution is erroneous if a subprogram is invoked as 12850part of its execution. 12851 12852@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 12853@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e9} 12854@subsection No_Reentrancy 12855 12856 12857@geindex No_Reentrancy 12858 12859[RM H.4] A program execution is erroneous if a subprogram is executed by 12860two tasks at the same time. 12861 12862@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 12863@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1ea} 12864@subsection No_Relative_Delay 12865 12866 12867@geindex No_Relative_Delay 12868 12869[RM D.7] This restriction ensures at compile time that there are no delay 12870relative statements and prevents expressions such as @code{delay 1.23;} from 12871appearing in source code. 12872 12873@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 12874@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1eb} 12875@subsection No_Requeue_Statements 12876 12877 12878@geindex No_Requeue_Statements 12879 12880[RM D.7] This restriction ensures at compile time that no requeue statements 12881are permitted and prevents keyword @code{requeue} from being used in source 12882code. 12883 12884@geindex No_Requeue 12885 12886The restriction @code{No_Requeue} is recognized as a 12887synonym for @code{No_Requeue_Statements}. This is retained for historical 12888compatibility purposes (and a warning will be generated for its use if 12889warnings on oNobsolescent features are activated). 12890 12891@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 12892@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ec} 12893@subsection No_Secondary_Stack 12894 12895 12896@geindex No_Secondary_Stack 12897 12898[GNAT] This restriction ensures at compile time that the generated code 12899does not contain any reference to the secondary stack. The secondary 12900stack is used to implement functions returning unconstrained objects 12901(arrays or records) on some targets. Suppresses the allocation of 12902secondary stacks for tasks (excluding the environment task) at run time. 12903 12904@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 12905@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ed} 12906@subsection No_Select_Statements 12907 12908 12909@geindex No_Select_Statements 12910 12911[RM D.7] This restriction ensures at compile time no select statements of any 12912kind are permitted, that is the keyword @code{select} may not appear. 12913 12914@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 12915@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ee} 12916@subsection No_Specific_Termination_Handlers 12917 12918 12919@geindex No_Specific_Termination_Handlers 12920 12921[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 12922or to Ada.Task_Termination.Specific_Handler. 12923 12924@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 12925@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1ef} 12926@subsection No_Specification_of_Aspect 12927 12928 12929@geindex No_Specification_of_Aspect 12930 12931[RM 13.12.1] This restriction checks at compile time that no aspect 12932specification, attribute definition clause, or pragma is given for a 12933given aspect. 12934 12935@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 12936@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f0} 12937@subsection No_Standard_Allocators_After_Elaboration 12938 12939 12940@geindex No_Standard_Allocators_After_Elaboration 12941 12942[RM D.7] Specifies that an allocator using a standard storage pool 12943should never be evaluated at run time after the elaboration of the 12944library items of the partition has completed. Otherwise, Storage_Error 12945is raised. 12946 12947@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 12948@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f1} 12949@subsection No_Standard_Storage_Pools 12950 12951 12952@geindex No_Standard_Storage_Pools 12953 12954[GNAT] This restriction ensures at compile time that no access types 12955use the standard default storage pool. Any access type declared must 12956have an explicit Storage_Pool attribute defined specifying a 12957user-defined storage pool. 12958 12959@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 12960@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f2} 12961@subsection No_Stream_Optimizations 12962 12963 12964@geindex No_Stream_Optimizations 12965 12966[GNAT] This restriction affects the performance of stream operations on types 12967@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 12968compiler uses block reads and writes when manipulating @code{String} objects 12969due to their superior performance. When this restriction is in effect, the 12970compiler performs all IO operations on a per-character basis. 12971 12972@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 12973@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f3} 12974@subsection No_Streams 12975 12976 12977@geindex No_Streams 12978 12979[GNAT] This restriction ensures at compile/bind time that there are no 12980stream objects created and no use of stream attributes. 12981This restriction does not forbid dependences on the package 12982@code{Ada.Streams}. So it is permissible to with 12983@code{Ada.Streams} (or another package that does so itself) 12984as long as no actual stream objects are created and no 12985stream attributes are used. 12986 12987Note that the use of restriction allows optimization of tagged types, 12988since they do not need to worry about dispatching stream operations. 12989To take maximum advantage of this space-saving optimization, any 12990unit declaring a tagged type should be compiled with the restriction, 12991though this is not required. 12992 12993@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 12994@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f4} 12995@subsection No_Task_Allocators 12996 12997 12998@geindex No_Task_Allocators 12999 13000[RM D.7] There are no allocators for task types 13001or types containing task subcomponents. 13002 13003@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 13004@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f5} 13005@subsection No_Task_At_Interrupt_Priority 13006 13007 13008@geindex No_Task_At_Interrupt_Priority 13009 13010[GNAT] This restriction ensures at compile time that there is no 13011Interrupt_Priority aspect or pragma for a task or a task type. As 13012a consequence, the tasks are always created with a priority below 13013that an interrupt priority. 13014 13015@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 13016@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f6} 13017@subsection No_Task_Attributes_Package 13018 13019 13020@geindex No_Task_Attributes_Package 13021 13022[GNAT] This restriction ensures at compile time that there are no implicit or 13023explicit dependencies on the package @code{Ada.Task_Attributes}. 13024 13025@geindex No_Task_Attributes 13026 13027The restriction @code{No_Task_Attributes} is recognized as a synonym 13028for @code{No_Task_Attributes_Package}. This is retained for historical 13029compatibility purposes (and a warning will be generated for its use if 13030warnings on obsolescent features are activated). 13031 13032@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 13033@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f7} 13034@subsection No_Task_Hierarchy 13035 13036 13037@geindex No_Task_Hierarchy 13038 13039[RM D.7] All (non-environment) tasks depend 13040directly on the environment task of the partition. 13041 13042@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 13043@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f8} 13044@subsection No_Task_Termination 13045 13046 13047@geindex No_Task_Termination 13048 13049[RM D.7] Tasks that terminate are erroneous. 13050 13051@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 13052@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1f9} 13053@subsection No_Tasking 13054 13055 13056@geindex No_Tasking 13057 13058[GNAT] This restriction prevents the declaration of tasks or task types 13059throughout the partition. It is similar in effect to the use of 13060@code{Max_Tasks => 0} except that violations are caught at compile time 13061and cause an error message to be output either by the compiler or 13062binder. 13063 13064@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 13065@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fa} 13066@subsection No_Terminate_Alternatives 13067 13068 13069@geindex No_Terminate_Alternatives 13070 13071[RM D.7] There are no selective accepts with terminate alternatives. 13072 13073@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 13074@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fb} 13075@subsection No_Unchecked_Access 13076 13077 13078@geindex No_Unchecked_Access 13079 13080[RM H.4] This restriction ensures at compile time that there are no 13081occurrences of the Unchecked_Access attribute. 13082 13083@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 13084@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fc} 13085@subsection No_Unchecked_Conversion 13086 13087 13088@geindex No_Unchecked_Conversion 13089 13090[RM J.13] This restriction ensures at compile time that there are no semantic 13091dependences on the predefined generic function Unchecked_Conversion. 13092 13093@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 13094@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fd} 13095@subsection No_Unchecked_Deallocation 13096 13097 13098@geindex No_Unchecked_Deallocation 13099 13100[RM J.13] This restriction ensures at compile time that there are no semantic 13101dependences on the predefined generic procedure Unchecked_Deallocation. 13102 13103@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 13104@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1fe} 13105@subsection No_Use_Of_Entity 13106 13107 13108@geindex No_Use_Of_Entity 13109 13110[GNAT] This restriction ensures at compile time that there are no references 13111to the entity given in the form 13112 13113@example 13114No_Use_Of_Entity => Name 13115@end example 13116 13117where @code{Name} is the fully qualified entity, for example 13118 13119@example 13120No_Use_Of_Entity => Ada.Text_IO.Put_Line 13121@end example 13122 13123@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 13124@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1ff} 13125@subsection Pure_Barriers 13126 13127 13128@geindex Pure_Barriers 13129 13130[GNAT] This restriction ensures at compile time that protected entry 13131barriers are restricted to: 13132 13133 13134@itemize * 13135 13136@item 13137components of the protected object (excluding selection from dereferences), 13138 13139@item 13140constant declarations, 13141 13142@item 13143named numbers, 13144 13145@item 13146enumeration literals, 13147 13148@item 13149integer literals, 13150 13151@item 13152real literals, 13153 13154@item 13155character literals, 13156 13157@item 13158implicitly defined comparison operators, 13159 13160@item 13161uses of the Standard."not" operator, 13162 13163@item 13164short-circuit operator, 13165 13166@item 13167the Count attribute 13168@end itemize 13169 13170This restriction is a relaxation of the Simple_Barriers restriction, 13171but still ensures absence of side effects, exceptions, and recursion 13172during the evaluation of the barriers. 13173 13174@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 13175@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{200} 13176@subsection Simple_Barriers 13177 13178 13179@geindex Simple_Barriers 13180 13181[RM D.7] This restriction ensures at compile time that barriers in entry 13182declarations for protected types are restricted to either static boolean 13183expressions or references to simple boolean variables defined in the private 13184part of the protected type. No other form of entry barriers is permitted. 13185 13186@geindex Boolean_Entry_Barriers 13187 13188The restriction @code{Boolean_Entry_Barriers} is recognized as a 13189synonym for @code{Simple_Barriers}. This is retained for historical 13190compatibility purposes (and a warning will be generated for its use if 13191warnings on obsolescent features are activated). 13192 13193@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 13194@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{201} 13195@subsection Static_Priorities 13196 13197 13198@geindex Static_Priorities 13199 13200[GNAT] This restriction ensures at compile time that all priority expressions 13201are static, and that there are no dependences on the package 13202@code{Ada.Dynamic_Priorities}. 13203 13204@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 13205@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{202} 13206@subsection Static_Storage_Size 13207 13208 13209@geindex Static_Storage_Size 13210 13211[GNAT] This restriction ensures at compile time that any expression appearing 13212in a Storage_Size pragma or attribute definition clause is static. 13213 13214@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 13215@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{203}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{204} 13216@section Program Unit Level Restrictions 13217 13218 13219The second set of restriction identifiers 13220does not require partition-wide consistency. 13221The restriction may be enforced for a single 13222compilation unit without any effect on any of the 13223other compilation units in the partition. 13224 13225@menu 13226* No_Elaboration_Code:: 13227* No_Dynamic_Sized_Objects:: 13228* No_Entry_Queue:: 13229* No_Implementation_Aspect_Specifications:: 13230* No_Implementation_Attributes:: 13231* No_Implementation_Identifiers:: 13232* No_Implementation_Pragmas:: 13233* No_Implementation_Restrictions:: 13234* No_Implementation_Units:: 13235* No_Implicit_Aliasing:: 13236* No_Implicit_Loops:: 13237* No_Obsolescent_Features:: 13238* No_Wide_Characters:: 13239* Static_Dispatch_Tables:: 13240* SPARK_05:: 13241 13242@end menu 13243 13244@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions 13245@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{205} 13246@subsection No_Elaboration_Code 13247 13248 13249@geindex No_Elaboration_Code 13250 13251[GNAT] This restriction ensures at compile time that no elaboration code is 13252generated. Note that this is not the same condition as is enforced 13253by pragma @code{Preelaborate}. There are cases in which pragma 13254@code{Preelaborate} still permits code to be generated (e.g., code 13255to initialize a large array to all zeroes), and there are cases of units 13256which do not meet the requirements for pragma @code{Preelaborate}, 13257but for which no elaboration code is generated. Generally, it is 13258the case that preelaborable units will meet the restrictions, with 13259the exception of large aggregates initialized with an others_clause, 13260and exception declarations (which generate calls to a run-time 13261registry procedure). This restriction is enforced on 13262a unit by unit basis, it need not be obeyed consistently 13263throughout a partition. 13264 13265In the case of aggregates with others, if the aggregate has a dynamic 13266size, there is no way to eliminate the elaboration code (such dynamic 13267bounds would be incompatible with @code{Preelaborate} in any case). If 13268the bounds are static, then use of this restriction actually modifies 13269the code choice of the compiler to avoid generating a loop, and instead 13270generate the aggregate statically if possible, no matter how many times 13271the data for the others clause must be repeatedly generated. 13272 13273It is not possible to precisely document 13274the constructs which are compatible with this restriction, since, 13275unlike most other restrictions, this is not a restriction on the 13276source code, but a restriction on the generated object code. For 13277example, if the source contains a declaration: 13278 13279@example 13280Val : constant Integer := X; 13281@end example 13282 13283where X is not a static constant, it may be possible, depending 13284on complex optimization circuitry, for the compiler to figure 13285out the value of X at compile time, in which case this initialization 13286can be done by the loader, and requires no initialization code. It 13287is not possible to document the precise conditions under which the 13288optimizer can figure this out. 13289 13290Note that this the implementation of this restriction requires full 13291code generation. If it is used in conjunction with "semantics only" 13292checking, then some cases of violations may be missed. 13293 13294When this restriction is active, we are not requesting control-flow 13295preservation with -fpreserve-control-flow, and the static elaboration model is 13296used, the compiler is allowed to suppress the elaboration counter normally 13297associated with the unit. This counter is typically used to check for access 13298before elaboration and to control multiple elaboration attempts. 13299 13300@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions 13301@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{206} 13302@subsection No_Dynamic_Sized_Objects 13303 13304 13305@geindex No_Dynamic_Sized_Objects 13306 13307[GNAT] This restriction disallows certain constructs that might lead to the 13308creation of dynamic-sized composite objects (or array or discriminated type). 13309An array subtype indication is illegal if the bounds are not static 13310or references to discriminants of an enclosing type. 13311A discriminated subtype indication is illegal if the type has 13312discriminant-dependent array components or a variant part, and the 13313discriminants are not static. In addition, array and record aggregates are 13314illegal in corresponding cases. Note that this restriction does not forbid 13315access discriminants. It is often a good idea to combine this restriction 13316with No_Secondary_Stack. 13317 13318@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 13319@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{207} 13320@subsection No_Entry_Queue 13321 13322 13323@geindex No_Entry_Queue 13324 13325[GNAT] This restriction is a declaration that any protected entry compiled in 13326the scope of the restriction has at most one task waiting on the entry 13327at any one time, and so no queue is required. This restriction is not 13328checked at compile time. A program execution is erroneous if an attempt 13329is made to queue a second task on such an entry. 13330 13331@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 13332@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{208} 13333@subsection No_Implementation_Aspect_Specifications 13334 13335 13336@geindex No_Implementation_Aspect_Specifications 13337 13338[RM 13.12.1] This restriction checks at compile time that no 13339GNAT-defined aspects are present. With this restriction, the only 13340aspects that can be used are those defined in the Ada Reference Manual. 13341 13342@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 13343@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{209} 13344@subsection No_Implementation_Attributes 13345 13346 13347@geindex No_Implementation_Attributes 13348 13349[RM 13.12.1] This restriction checks at compile time that no 13350GNAT-defined attributes are present. With this restriction, the only 13351attributes that can be used are those defined in the Ada Reference 13352Manual. 13353 13354@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 13355@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20a} 13356@subsection No_Implementation_Identifiers 13357 13358 13359@geindex No_Implementation_Identifiers 13360 13361[RM 13.12.1] This restriction checks at compile time that no 13362implementation-defined identifiers (marked with pragma Implementation_Defined) 13363occur within language-defined packages. 13364 13365@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 13366@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20b} 13367@subsection No_Implementation_Pragmas 13368 13369 13370@geindex No_Implementation_Pragmas 13371 13372[RM 13.12.1] This restriction checks at compile time that no 13373GNAT-defined pragmas are present. With this restriction, the only 13374pragmas that can be used are those defined in the Ada Reference Manual. 13375 13376@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 13377@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20c} 13378@subsection No_Implementation_Restrictions 13379 13380 13381@geindex No_Implementation_Restrictions 13382 13383[GNAT] This restriction checks at compile time that no GNAT-defined restriction 13384identifiers (other than @code{No_Implementation_Restrictions} itself) 13385are present. With this restriction, the only other restriction identifiers 13386that can be used are those defined in the Ada Reference Manual. 13387 13388@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 13389@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20d} 13390@subsection No_Implementation_Units 13391 13392 13393@geindex No_Implementation_Units 13394 13395[RM 13.12.1] This restriction checks at compile time that there is no 13396mention in the context clause of any implementation-defined descendants 13397of packages Ada, Interfaces, or System. 13398 13399@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions 13400@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{20e} 13401@subsection No_Implicit_Aliasing 13402 13403 13404@geindex No_Implicit_Aliasing 13405 13406[GNAT] This restriction, which is not required to be partition-wide consistent, 13407requires an explicit aliased keyword for an object to which 'Access, 13408'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 13409the 'Unrestricted_Access attribute for objects. Note: the reason that 13410Unrestricted_Access is forbidden is that it would require the prefix 13411to be aliased, and in such cases, it can always be replaced by 13412the standard attribute Unchecked_Access which is preferable. 13413 13414@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions 13415@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{20f} 13416@subsection No_Implicit_Loops 13417 13418 13419@geindex No_Implicit_Loops 13420 13421[GNAT] This restriction ensures that the generated code of the unit marked 13422with this restriction does not contain any implicit @code{for} loops, either by 13423modifying the generated code where possible, or by rejecting any construct 13424that would otherwise generate an implicit @code{for} loop. If this restriction is 13425active, it is possible to build large array aggregates with all static 13426components without generating an intermediate temporary, and without generating 13427a loop to initialize individual components. Otherwise, a loop is created for 13428arrays larger than about 5000 scalar components. Note that if this restriction 13429is set in the spec of a package, it will not apply to its body. 13430 13431@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions 13432@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{210} 13433@subsection No_Obsolescent_Features 13434 13435 13436@geindex No_Obsolescent_Features 13437 13438[RM 13.12.1] This restriction checks at compile time that no obsolescent 13439features are used, as defined in Annex J of the Ada Reference Manual. 13440 13441@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions 13442@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{211} 13443@subsection No_Wide_Characters 13444 13445 13446@geindex No_Wide_Characters 13447 13448[GNAT] This restriction ensures at compile time that no uses of the types 13449@code{Wide_Character} or @code{Wide_String} or corresponding wide 13450wide types 13451appear, and that no wide or wide wide string or character literals 13452appear in the program (that is literals representing characters not in 13453type @code{Character}). 13454 13455@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions 13456@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{212} 13457@subsection Static_Dispatch_Tables 13458 13459 13460@geindex Static_Dispatch_Tables 13461 13462[GNAT] This restriction checks at compile time that all the artifacts 13463associated with dispatch tables can be placed in read-only memory. 13464 13465@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions 13466@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{213} 13467@subsection SPARK_05 13468 13469 13470@geindex SPARK_05 13471 13472[GNAT] This restriction checks at compile time that some constructs forbidden 13473in SPARK 2005 are not present. Note that SPARK 2005 has been superseded by 13474SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that 13475a codebase respects SPARK 2014 restrictions, mark the code with pragma or 13476aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as 13477follows: 13478 13479@example 13480gnatprove -P project.gpr --mode=stone 13481@end example 13482 13483or equivalently: 13484 13485@example 13486gnatprove -P project.gpr --mode=check_all 13487@end example 13488 13489With restriction @code{SPARK_05}, error messages related to SPARK 2005 restriction 13490have the form: 13491 13492@example 13493violation of restriction "SPARK_05" at <source-location> 13494 <error message> 13495@end example 13496 13497@geindex SPARK 13498 13499The restriction @code{SPARK} is recognized as a synonym for @code{SPARK_05}. This is 13500retained for historical compatibility purposes (and an unconditional warning 13501will be generated for its use, advising replacement by @code{SPARK_05}). 13502 13503This is not a replacement for the semantic checks performed by the 13504SPARK Examiner tool, as the compiler currently only deals with code, 13505not SPARK 2005 annotations, and does not guarantee catching all 13506cases of constructs forbidden by SPARK 2005. 13507 13508Thus it may well be the case that code which passes the compiler with 13509the SPARK 2005 restriction is rejected by the SPARK Examiner, e.g. due to 13510the different visibility rules of the Examiner based on SPARK 2005 13511@code{inherit} annotations. 13512 13513This restriction can be useful in providing an initial filter for code 13514developed using SPARK 2005, or in examining legacy code to see how far 13515it is from meeting SPARK 2005 restrictions. 13516 13517The list below summarizes the checks that are performed when this 13518restriction is in force: 13519 13520 13521@itemize * 13522 13523@item 13524No block statements 13525 13526@item 13527No case statements with only an others clause 13528 13529@item 13530Exit statements in loops must respect the SPARK 2005 language restrictions 13531 13532@item 13533No goto statements 13534 13535@item 13536Return can only appear as last statement in function 13537 13538@item 13539Function must have return statement 13540 13541@item 13542Loop parameter specification must include subtype mark 13543 13544@item 13545Prefix of expanded name cannot be a loop statement 13546 13547@item 13548Abstract subprogram not allowed 13549 13550@item 13551User-defined operators not allowed 13552 13553@item 13554Access type parameters not allowed 13555 13556@item 13557Default expressions for parameters not allowed 13558 13559@item 13560Default expressions for record fields not allowed 13561 13562@item 13563No tasking constructs allowed 13564 13565@item 13566Label needed at end of subprograms and packages 13567 13568@item 13569No mixing of positional and named parameter association 13570 13571@item 13572No access types as result type 13573 13574@item 13575No unconstrained arrays as result types 13576 13577@item 13578No null procedures 13579 13580@item 13581Initial and later declarations must be in correct order (declaration can't come after body) 13582 13583@item 13584No attributes on private types if full declaration not visible 13585 13586@item 13587No package declaration within package specification 13588 13589@item 13590No controlled types 13591 13592@item 13593No discriminant types 13594 13595@item 13596No overloading 13597 13598@item 13599Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed) 13600 13601@item 13602Access attribute not allowed 13603 13604@item 13605Allocator not allowed 13606 13607@item 13608Result of catenation must be String 13609 13610@item 13611Operands of catenation must be string literal, static char or another catenation 13612 13613@item 13614No conditional expressions 13615 13616@item 13617No explicit dereference 13618 13619@item 13620Quantified expression not allowed 13621 13622@item 13623Slicing not allowed 13624 13625@item 13626No exception renaming 13627 13628@item 13629No generic renaming 13630 13631@item 13632No object renaming 13633 13634@item 13635No use clause 13636 13637@item 13638Aggregates must be qualified 13639 13640@item 13641Nonstatic choice in array aggregates not allowed 13642 13643@item 13644The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type 13645 13646@item 13647No mixing of positional and named association in aggregate, no multi choice 13648 13649@item 13650AND, OR and XOR for arrays only allowed when operands have same static bounds 13651 13652@item 13653Fixed point operands to * or / must be qualified or converted 13654 13655@item 13656Comparison operators not allowed for Booleans or arrays (except strings) 13657 13658@item 13659Equality not allowed for arrays with non-matching static bounds (except strings) 13660 13661@item 13662Conversion / qualification not allowed for arrays with non-matching static bounds 13663 13664@item 13665Subprogram declaration only allowed in package spec (unless followed by import) 13666 13667@item 13668Access types not allowed 13669 13670@item 13671Incomplete type declaration not allowed 13672 13673@item 13674Object and subtype declarations must respect SPARK 2005 restrictions 13675 13676@item 13677Digits or delta constraint not allowed 13678 13679@item 13680Decimal fixed point type not allowed 13681 13682@item 13683Aliasing of objects not allowed 13684 13685@item 13686Modular type modulus must be power of 2 13687 13688@item 13689Base not allowed on subtype mark 13690 13691@item 13692Unary operators not allowed on modular types (except not) 13693 13694@item 13695Untagged record cannot be null 13696 13697@item 13698No class-wide operations 13699 13700@item 13701Initialization expressions must respect SPARK 2005 restrictions 13702 13703@item 13704Nonstatic ranges not allowed except in iteration schemes 13705 13706@item 13707String subtypes must have lower bound of 1 13708 13709@item 13710Subtype of Boolean cannot have constraint 13711 13712@item 13713At most one tagged type or extension per package 13714 13715@item 13716Interface is not allowed 13717 13718@item 13719Character literal cannot be prefixed (selector name cannot be character literal) 13720 13721@item 13722Record aggregate cannot contain 'others' 13723 13724@item 13725Component association in record aggregate must contain a single choice 13726 13727@item 13728Ancestor part cannot be a type mark 13729 13730@item 13731Attributes 'Image, 'Width and 'Value not allowed 13732 13733@item 13734Functions may not update globals 13735 13736@item 13737Subprograms may not contain direct calls to themselves (prevents recursion within unit) 13738 13739@item 13740Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit) 13741@end itemize 13742 13743The following restrictions are enforced, but note that they are actually more 13744strict that the latest SPARK 2005 language definition: 13745 13746 13747@itemize * 13748 13749@item 13750No derived types other than tagged type extensions 13751 13752@item 13753Subtype of unconstrained array must have constraint 13754@end itemize 13755 13756This list summarises the main SPARK 2005 language rules that are not 13757currently checked by the SPARK_05 restriction: 13758 13759 13760@itemize * 13761 13762@item 13763SPARK 2005 annotations are treated as comments so are not checked at all 13764 13765@item 13766Based real literals not allowed 13767 13768@item 13769Objects cannot be initialized at declaration by calls to user-defined functions 13770 13771@item 13772Objects cannot be initialized at declaration by assignments from variables 13773 13774@item 13775Objects cannot be initialized at declaration by assignments from indexed/selected components 13776 13777@item 13778Ranges shall not be null 13779 13780@item 13781A fixed point delta expression must be a simple expression 13782 13783@item 13784Restrictions on where renaming declarations may be placed 13785 13786@item 13787Externals of mode 'out' cannot be referenced 13788 13789@item 13790Externals of mode 'in' cannot be updated 13791 13792@item 13793Loop with no iteration scheme or exits only allowed as last statement in main program or task 13794 13795@item 13796Subprogram cannot have parent unit name 13797 13798@item 13799SPARK 2005 inherited subprogram must be prefixed with overriding 13800 13801@item 13802External variables (or functions that reference them) may not be passed as actual parameters 13803 13804@item 13805Globals must be explicitly mentioned in contract 13806 13807@item 13808Deferred constants cannot be completed by pragma Import 13809 13810@item 13811Package initialization cannot read/write variables from other packages 13812 13813@item 13814Prefix not allowed for entities that are directly visible 13815 13816@item 13817Identifier declaration can't override inherited package name 13818 13819@item 13820Cannot use Standard or other predefined packages as identifiers 13821 13822@item 13823After renaming, cannot use the original name 13824 13825@item 13826Subprograms can only be renamed to remove package prefix 13827 13828@item 13829Pragma import must be immediately after entity it names 13830 13831@item 13832No mutual recursion between multiple units (this can be checked with gnatcheck) 13833@end itemize 13834 13835Note that if a unit is compiled in Ada 95 mode with the SPARK 2005 restriction, 13836violations will be reported for constructs forbidden in SPARK 95, 13837instead of SPARK 2005. 13838 13839@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13840@anchor{gnat_rm/implementation_advice doc}@anchor{214}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{215} 13841@chapter Implementation Advice 13842 13843 13844The main text of the Ada Reference Manual describes the required 13845behavior of all Ada compilers, and the GNAT compiler conforms to 13846these requirements. 13847 13848In addition, there are sections throughout the Ada Reference Manual headed 13849by the phrase 'Implementation advice'. These sections are not normative, 13850i.e., they do not specify requirements that all compilers must 13851follow. Rather they provide advice on generally desirable behavior. 13852They are not requirements, because they describe behavior that cannot 13853be provided on all systems, or may be undesirable on some systems. 13854 13855As far as practical, GNAT follows the implementation advice in 13856the Ada Reference Manual. Each such RM section corresponds to a section 13857in this chapter whose title specifies the 13858RM section number and paragraph number and the subject of 13859the advice. The contents of each section consists of the RM text within 13860quotation marks, 13861followed by the GNAT interpretation of the advice. Most often, this simply says 13862'followed', which means that GNAT follows the advice. However, in a 13863number of cases, GNAT deliberately deviates from this advice, in which 13864case the text describes what GNAT does and why. 13865 13866@geindex Error detection 13867 13868@menu 13869* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13870* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13871* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13872* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13873* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13874* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13875* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13876* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13877* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13878* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13879* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13880* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 13881* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13882* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13883* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13884* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13885* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13886* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13887* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13888* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13889* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13890* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13891* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13892* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13893* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13894* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13895* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13896* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13897* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13898* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13899* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13900* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 13901* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13902* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13903* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13904* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13905* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13906* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13907* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13908* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13909* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13910* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13911* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13912* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13913* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13914* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13915* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13916* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13917* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13918* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13919* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13920* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13921* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13922* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13923* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13924* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13925* RM F(7); COBOL Support: RM F 7 COBOL Support. 13926* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13927* RM G; Numerics: RM G Numerics. 13928* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13929* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13930* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13931* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13932* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13933 13934@end menu 13935 13936@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13937@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{216} 13938@section RM 1.1.3(20): Error Detection 13939 13940 13941@quotation 13942 13943"If an implementation detects the use of an unsupported Specialized Needs 13944Annex feature at run time, it should raise @code{Program_Error} if 13945feasible." 13946@end quotation 13947 13948Not relevant. All specialized needs annex features are either supported, 13949or diagnosed at compile time. 13950 13951@geindex Child Units 13952 13953@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13954@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{217} 13955@section RM 1.1.3(31): Child Units 13956 13957 13958@quotation 13959 13960"If an implementation wishes to provide implementation-defined 13961extensions to the functionality of a language-defined library unit, it 13962should normally do so by adding children to the library unit." 13963@end quotation 13964 13965Followed. 13966 13967@geindex Bounded errors 13968 13969@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13970@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{218} 13971@section RM 1.1.5(12): Bounded Errors 13972 13973 13974@quotation 13975 13976"If an implementation detects a bounded error or erroneous 13977execution, it should raise @code{Program_Error}." 13978@end quotation 13979 13980Followed in all cases in which the implementation detects a bounded 13981error or erroneous execution. Not all such situations are detected at 13982runtime. 13983 13984@geindex Pragmas 13985 13986@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13987@anchor{gnat_rm/implementation_advice id2}@anchor{219}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21a} 13988@section RM 2.8(16): Pragmas 13989 13990 13991@quotation 13992 13993"Normally, implementation-defined pragmas should have no semantic effect 13994for error-free programs; that is, if the implementation-defined pragmas 13995are removed from a working program, the program should still be legal, 13996and should still have the same semantics." 13997@end quotation 13998 13999The following implementation defined pragmas are exceptions to this 14000rule: 14001 14002 14003@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 14004@headitem 14005 14006Pragma 14007 14008@tab 14009 14010Explanation 14011 14012@item 14013 14014@emph{Abort_Defer} 14015 14016@tab 14017 14018Affects semantics 14019 14020@item 14021 14022@emph{Ada_83} 14023 14024@tab 14025 14026Affects legality 14027 14028@item 14029 14030@emph{Assert} 14031 14032@tab 14033 14034Affects semantics 14035 14036@item 14037 14038@emph{CPP_Class} 14039 14040@tab 14041 14042Affects semantics 14043 14044@item 14045 14046@emph{CPP_Constructor} 14047 14048@tab 14049 14050Affects semantics 14051 14052@item 14053 14054@emph{Debug} 14055 14056@tab 14057 14058Affects semantics 14059 14060@item 14061 14062@emph{Interface_Name} 14063 14064@tab 14065 14066Affects semantics 14067 14068@item 14069 14070@emph{Machine_Attribute} 14071 14072@tab 14073 14074Affects semantics 14075 14076@item 14077 14078@emph{Unimplemented_Unit} 14079 14080@tab 14081 14082Affects legality 14083 14084@item 14085 14086@emph{Unchecked_Union} 14087 14088@tab 14089 14090Affects semantics 14091 14092@end multitable 14093 14094 14095In each of the above cases, it is essential to the purpose of the pragma 14096that this advice not be followed. For details see 14097@ref{7,,Implementation Defined Pragmas}. 14098 14099@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 14100@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21b} 14101@section RM 2.8(17-19): Pragmas 14102 14103 14104@quotation 14105 14106"Normally, an implementation should not define pragmas that can 14107make an illegal program legal, except as follows: 14108 14109 14110@itemize * 14111 14112@item 14113A pragma used to complete a declaration, such as a pragma @code{Import}; 14114 14115@item 14116A pragma used to configure the environment by adding, removing, or 14117replacing @code{library_items}." 14118@end itemize 14119@end quotation 14120 14121See @ref{21a,,RM 2.8(16); Pragmas}. 14122 14123@geindex Character Sets 14124 14125@geindex Alternative Character Sets 14126 14127@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 14128@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21c} 14129@section RM 3.5.2(5): Alternative Character Sets 14130 14131 14132@quotation 14133 14134"If an implementation supports a mode with alternative interpretations 14135for @code{Character} and @code{Wide_Character}, the set of graphic 14136characters of @code{Character} should nevertheless remain a proper 14137subset of the set of graphic characters of @code{Wide_Character}. Any 14138character set 'localizations' should be reflected in the results of 14139the subprograms defined in the language-defined package 14140@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 14141an alternative interpretation of @code{Character}, the implementation should 14142also support a corresponding change in what is a legal 14143@code{identifier_letter}." 14144@end quotation 14145 14146Not all wide character modes follow this advice, in particular the JIS 14147and IEC modes reflect standard usage in Japan, and in these encoding, 14148the upper half of the Latin-1 set is not part of the wide-character 14149subset, since the most significant bit is used for wide character 14150encoding. However, this only applies to the external forms. Internally 14151there is no such restriction. 14152 14153@geindex Integer types 14154 14155@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 14156@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21d} 14157@section RM 3.5.4(28): Integer Types 14158 14159 14160@quotation 14161 14162"An implementation should support @code{Long_Integer} in addition to 14163@code{Integer} if the target machine supports 32-bit (or longer) 14164arithmetic. No other named integer subtypes are recommended for package 14165@code{Standard}. Instead, appropriate named integer subtypes should be 14166provided in the library package @code{Interfaces} (see B.2)." 14167@end quotation 14168 14169@code{Long_Integer} is supported. Other standard integer types are supported 14170so this advice is not fully followed. These types 14171are supported for convenient interface to C, and so that all hardware 14172types of the machine are easily available. 14173 14174@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 14175@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{21e} 14176@section RM 3.5.4(29): Integer Types 14177 14178 14179@quotation 14180 14181"An implementation for a two's complement machine should support 14182modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 14183implementation should support a non-binary modules up to @code{Integer'Last}." 14184@end quotation 14185 14186Followed. 14187 14188@geindex Enumeration values 14189 14190@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 14191@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{21f} 14192@section RM 3.5.5(8): Enumeration Values 14193 14194 14195@quotation 14196 14197"For the evaluation of a call on @code{S'Pos} for an enumeration 14198subtype, if the value of the operand does not correspond to the internal 14199code for any enumeration literal of its type (perhaps due to an 14200un-initialized variable), then the implementation should raise 14201@code{Program_Error}. This is particularly important for enumeration 14202types with noncontiguous internal codes specified by an 14203enumeration_representation_clause." 14204@end quotation 14205 14206Followed. 14207 14208@geindex Float types 14209 14210@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 14211@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{220} 14212@section RM 3.5.7(17): Float Types 14213 14214 14215@quotation 14216 14217"An implementation should support @code{Long_Float} in addition to 14218@code{Float} if the target machine supports 11 or more digits of 14219precision. No other named floating point subtypes are recommended for 14220package @code{Standard}. Instead, appropriate named floating point subtypes 14221should be provided in the library package @code{Interfaces} (see B.2)." 14222@end quotation 14223 14224@code{Short_Float} and @code{Long_Long_Float} are also provided. The 14225former provides improved compatibility with other implementations 14226supporting this type. The latter corresponds to the highest precision 14227floating-point type supported by the hardware. On most machines, this 14228will be the same as @code{Long_Float}, but on some machines, it will 14229correspond to the IEEE extended form. The notable case is all ia32 14230(x86) implementations, where @code{Long_Long_Float} corresponds to 14231the 80-bit extended precision format supported in hardware on this 14232processor. Note that the 128-bit format on SPARC is not supported, 14233since this is a software rather than a hardware format. 14234 14235@geindex Multidimensional arrays 14236 14237@geindex Arrays 14238@geindex multidimensional 14239 14240@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice 14241@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{221} 14242@section RM 3.6.2(11): Multidimensional Arrays 14243 14244 14245@quotation 14246 14247"An implementation should normally represent multidimensional arrays in 14248row-major order, consistent with the notation used for multidimensional 14249array aggregates (see 4.3.3). However, if a pragma @code{Convention} 14250(@code{Fortran}, ...) applies to a multidimensional array type, then 14251column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})." 14252@end quotation 14253 14254Followed. 14255 14256@geindex Duration'Small 14257 14258@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 14259@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{222} 14260@section RM 9.6(30-31): Duration'Small 14261 14262 14263@quotation 14264 14265"Whenever possible in an implementation, the value of @code{Duration'Small} 14266should be no greater than 100 microseconds." 14267@end quotation 14268 14269Followed. (@code{Duration'Small} = 10**(-9)). 14270 14271@quotation 14272 14273"The time base for @code{delay_relative_statements} should be monotonic; 14274it need not be the same time base as used for @code{Calendar.Clock}." 14275@end quotation 14276 14277Followed. 14278 14279@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice 14280@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{223} 14281@section RM 10.2.1(12): Consistent Representation 14282 14283 14284@quotation 14285 14286"In an implementation, a type declared in a pre-elaborated package should 14287have the same representation in every elaboration of a given version of 14288the package, whether the elaborations occur in distinct executions of 14289the same program, or in executions of distinct programs or partitions 14290that include the given version." 14291@end quotation 14292 14293Followed, except in the case of tagged types. Tagged types involve 14294implicit pointers to a local copy of a dispatch table, and these pointers 14295have representations which thus depend on a particular elaboration of the 14296package. It is not easy to see how it would be possible to follow this 14297advice without severely impacting efficiency of execution. 14298 14299@geindex Exception information 14300 14301@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 14302@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{224} 14303@section RM 11.4.1(19): Exception Information 14304 14305 14306@quotation 14307 14308"@code{Exception_Message} by default and @code{Exception_Information} 14309should produce information useful for 14310debugging. @code{Exception_Message} should be short, about one 14311line. @code{Exception_Information} can be long. @code{Exception_Message} 14312should not include the 14313@code{Exception_Name}. @code{Exception_Information} should include both 14314the @code{Exception_Name} and the @code{Exception_Message}." 14315@end quotation 14316 14317Followed. For each exception that doesn't have a specified 14318@code{Exception_Message}, the compiler generates one containing the location 14319of the raise statement. This location has the form 'file_name:line', where 14320file_name is the short file name (without path information) and line is the line 14321number in the file. Note that in the case of the Zero Cost Exception 14322mechanism, these messages become redundant with the Exception_Information that 14323contains a full backtrace of the calling sequence, so they are disabled. 14324To disable explicitly the generation of the source location message, use the 14325Pragma @code{Discard_Names}. 14326 14327@geindex Suppression of checks 14328 14329@geindex Checks 14330@geindex suppression of 14331 14332@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 14333@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{225} 14334@section RM 11.5(28): Suppression of Checks 14335 14336 14337@quotation 14338 14339"The implementation should minimize the code executed for checks that 14340have been suppressed." 14341@end quotation 14342 14343Followed. 14344 14345@geindex Representation clauses 14346 14347@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 14348@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{226} 14349@section RM 13.1 (21-24): Representation Clauses 14350 14351 14352@quotation 14353 14354"The recommended level of support for all representation items is 14355qualified as follows: 14356 14357An implementation need not support representation items containing 14358nonstatic expressions, except that an implementation should support a 14359representation item for a given entity if each nonstatic expression in 14360the representation item is a name that statically denotes a constant 14361declared before the entity." 14362@end quotation 14363 14364Followed. In fact, GNAT goes beyond the recommended level of support 14365by allowing nonstatic expressions in some representation clauses even 14366without the need to declare constants initialized with the values of 14367such expressions. 14368For example: 14369 14370@example 14371 X : Integer; 14372 Y : Float; 14373 for Y'Address use X'Address;>> 14374 14375 14376"An implementation need not support a specification for the `@w{`}Size`@w{`} 14377for a given composite subtype, nor the size or storage place for an 14378object (including a component) of a given composite subtype, unless the 14379constraints on the subtype and its composite subcomponents (if any) are 14380all static constraints." 14381@end example 14382 14383Followed. Size Clauses are not permitted on nonstatic components, as 14384described above. 14385 14386@quotation 14387 14388"An aliased component, or a component whose type is by-reference, should 14389always be allocated at an addressable location." 14390@end quotation 14391 14392Followed. 14393 14394@geindex Packed types 14395 14396@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 14397@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{227} 14398@section RM 13.2(6-8): Packed Types 14399 14400 14401@quotation 14402 14403"If a type is packed, then the implementation should try to minimize 14404storage allocated to objects of the type, possibly at the expense of 14405speed of accessing components, subject to reasonable complexity in 14406addressing calculations. 14407 14408The recommended level of support pragma @code{Pack} is: 14409 14410For a packed record type, the components should be packed as tightly as 14411possible subject to the Sizes of the component subtypes, and subject to 14412any @emph{record_representation_clause} that applies to the type; the 14413implementation may, but need not, reorder components or cross aligned 14414word boundaries to improve the packing. A component whose @code{Size} is 14415greater than the word size may be allocated an integral number of words." 14416@end quotation 14417 14418Followed. Tight packing of arrays is supported for all component sizes 14419up to 64-bits. If the array component size is 1 (that is to say, if 14420the component is a boolean type or an enumeration type with two values) 14421then values of the type are implicitly initialized to zero. This 14422happens both for objects of the packed type, and for objects that have a 14423subcomponent of the packed type. 14424 14425@quotation 14426 14427"An implementation should support Address clauses for imported 14428subprograms." 14429@end quotation 14430 14431Followed. 14432 14433@geindex Address clauses 14434 14435@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 14436@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{228} 14437@section RM 13.3(14-19): Address Clauses 14438 14439 14440@quotation 14441 14442"For an array @code{X}, @code{X'Address} should point at the first 14443component of the array, and not at the array bounds." 14444@end quotation 14445 14446Followed. 14447 14448@quotation 14449 14450"The recommended level of support for the @code{Address} attribute is: 14451 14452@code{X'Address} should produce a useful result if @code{X} is an 14453object that is aliased or of a by-reference type, or is an entity whose 14454@code{Address} has been specified." 14455@end quotation 14456 14457Followed. A valid address will be produced even if none of those 14458conditions have been met. If necessary, the object is forced into 14459memory to ensure the address is valid. 14460 14461@quotation 14462 14463"An implementation should support @code{Address} clauses for imported 14464subprograms." 14465@end quotation 14466 14467Followed. 14468 14469@quotation 14470 14471"Objects (including subcomponents) that are aliased or of a by-reference 14472type should be allocated on storage element boundaries." 14473@end quotation 14474 14475Followed. 14476 14477@quotation 14478 14479"If the @code{Address} of an object is specified, or it is imported or exported, 14480then the implementation should not perform optimizations based on 14481assumptions of no aliases." 14482@end quotation 14483 14484Followed. 14485 14486@geindex Alignment clauses 14487 14488@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 14489@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{229} 14490@section RM 13.3(29-35): Alignment Clauses 14491 14492 14493@quotation 14494 14495"The recommended level of support for the @code{Alignment} attribute for 14496subtypes is: 14497 14498An implementation should support specified Alignments that are factors 14499and multiples of the number of storage elements per word, subject to the 14500following:" 14501@end quotation 14502 14503Followed. 14504 14505@quotation 14506 14507"An implementation need not support specified Alignments for 14508combinations of Sizes and Alignments that cannot be easily 14509loaded and stored by available machine instructions." 14510@end quotation 14511 14512Followed. 14513 14514@quotation 14515 14516"An implementation need not support specified Alignments that are 14517greater than the maximum @code{Alignment} the implementation ever returns by 14518default." 14519@end quotation 14520 14521Followed. 14522 14523@quotation 14524 14525"The recommended level of support for the @code{Alignment} attribute for 14526objects is: 14527 14528Same as above, for subtypes, but in addition:" 14529@end quotation 14530 14531Followed. 14532 14533@quotation 14534 14535"For stand-alone library-level objects of statically constrained 14536subtypes, the implementation should support all alignments 14537supported by the target linker. For example, page alignment is likely to 14538be supported for such objects, but not for subtypes." 14539@end quotation 14540 14541Followed. 14542 14543@geindex Size clauses 14544 14545@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 14546@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22a} 14547@section RM 13.3(42-43): Size Clauses 14548 14549 14550@quotation 14551 14552"The recommended level of support for the @code{Size} attribute of 14553objects is: 14554 14555A @code{Size} clause should be supported for an object if the specified 14556@code{Size} is at least as large as its subtype's @code{Size}, and 14557corresponds to a size in storage elements that is a multiple of the 14558object's @code{Alignment} (if the @code{Alignment} is nonzero)." 14559@end quotation 14560 14561Followed. 14562 14563@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 14564@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22b} 14565@section RM 13.3(50-56): Size Clauses 14566 14567 14568@quotation 14569 14570"If the @code{Size} of a subtype is specified, and allows for efficient 14571independent addressability (see 9.10) on the target architecture, then 14572the @code{Size} of the following objects of the subtype should equal the 14573@code{Size} of the subtype: 14574 14575Aliased objects (including components)." 14576@end quotation 14577 14578Followed. 14579 14580@quotation 14581 14582"@cite{Size} clause on a composite subtype should not affect the 14583internal layout of components." 14584@end quotation 14585 14586Followed. But note that this can be overridden by use of the implementation 14587pragma Implicit_Packing in the case of packed arrays. 14588 14589@quotation 14590 14591"The recommended level of support for the @code{Size} attribute of subtypes is: 14592 14593The @code{Size} (if not specified) of a static discrete or fixed point 14594subtype should be the number of bits needed to represent each value 14595belonging to the subtype using an unbiased representation, leaving space 14596for a sign bit only if the subtype contains negative values. If such a 14597subtype is a first subtype, then an implementation should support a 14598specified @code{Size} for it that reflects this representation." 14599@end quotation 14600 14601Followed. 14602 14603@quotation 14604 14605"For a subtype implemented with levels of indirection, the @code{Size} 14606should include the size of the pointers, but not the size of what they 14607point at." 14608@end quotation 14609 14610Followed. 14611 14612@geindex Component_Size clauses 14613 14614@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 14615@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22c} 14616@section RM 13.3(71-73): Component Size Clauses 14617 14618 14619@quotation 14620 14621"The recommended level of support for the @code{Component_Size} 14622attribute is: 14623 14624An implementation need not support specified @code{Component_Sizes} that are 14625less than the @code{Size} of the component subtype." 14626@end quotation 14627 14628Followed. 14629 14630@quotation 14631 14632"An implementation should support specified Component_Sizes that 14633are factors and multiples of the word size. For such 14634Component_Sizes, the array should contain no gaps between 14635components. For other Component_Sizes (if supported), the array 14636should contain no gaps between components when packing is also 14637specified; the implementation should forbid this combination in cases 14638where it cannot support a no-gaps representation." 14639@end quotation 14640 14641Followed. 14642 14643@geindex Enumeration representation clauses 14644 14645@geindex Representation clauses 14646@geindex enumeration 14647 14648@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 14649@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22d} 14650@section RM 13.4(9-10): Enumeration Representation Clauses 14651 14652 14653@quotation 14654 14655"The recommended level of support for enumeration representation clauses 14656is: 14657 14658An implementation need not support enumeration representation clauses 14659for boolean types, but should at minimum support the internal codes in 14660the range @code{System.Min_Int .. System.Max_Int}." 14661@end quotation 14662 14663Followed. 14664 14665@geindex Record representation clauses 14666 14667@geindex Representation clauses 14668@geindex records 14669 14670@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 14671@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{22e} 14672@section RM 13.5.1(17-22): Record Representation Clauses 14673 14674 14675@quotation 14676 14677"The recommended level of support for 14678@emph{record_representation_clause}s is: 14679 14680An implementation should support storage places that can be extracted 14681with a load, mask, shift sequence of machine code, and set with a load, 14682shift, mask, store sequence, given the available machine instructions 14683and run-time model." 14684@end quotation 14685 14686Followed. 14687 14688@quotation 14689 14690"A storage place should be supported if its size is equal to the 14691@code{Size} of the component subtype, and it starts and ends on a 14692boundary that obeys the @code{Alignment} of the component subtype." 14693@end quotation 14694 14695Followed. 14696 14697@quotation 14698 14699"If the default bit ordering applies to the declaration of a given type, 14700then for a component whose subtype's @code{Size} is less than the word 14701size, any storage place that does not cross an aligned word boundary 14702should be supported." 14703@end quotation 14704 14705Followed. 14706 14707@quotation 14708 14709"An implementation may reserve a storage place for the tag field of a 14710tagged type, and disallow other components from overlapping that place." 14711@end quotation 14712 14713Followed. The storage place for the tag field is the beginning of the tagged 14714record, and its size is Address'Size. GNAT will reject an explicit component 14715clause for the tag field. 14716 14717@quotation 14718 14719"An implementation need not support a @emph{component_clause} for a 14720component of an extension part if the storage place is not after the 14721storage places of all components of the parent type, whether or not 14722those storage places had been specified." 14723@end quotation 14724 14725Followed. The above advice on record representation clauses is followed, 14726and all mentioned features are implemented. 14727 14728@geindex Storage place attributes 14729 14730@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 14731@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{22f} 14732@section RM 13.5.2(5): Storage Place Attributes 14733 14734 14735@quotation 14736 14737"If a component is represented using some form of pointer (such as an 14738offset) to the actual data of the component, and this data is contiguous 14739with the rest of the object, then the storage place attributes should 14740reflect the place of the actual data, not the pointer. If a component is 14741allocated discontinuously from the rest of the object, then a warning 14742should be generated upon reference to one of its storage place 14743attributes." 14744@end quotation 14745 14746Followed. There are no such components in GNAT. 14747 14748@geindex Bit ordering 14749 14750@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 14751@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{230} 14752@section RM 13.5.3(7-8): Bit Ordering 14753 14754 14755@quotation 14756 14757"The recommended level of support for the non-default bit ordering is: 14758 14759If @code{Word_Size} = @code{Storage_Unit}, then the implementation 14760should support the non-default bit ordering in addition to the default 14761bit ordering." 14762@end quotation 14763 14764Followed. Word size does not equal storage size in this implementation. 14765Thus non-default bit ordering is not supported. 14766 14767@geindex Address 14768@geindex as private type 14769 14770@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 14771@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{231} 14772@section RM 13.7(37): Address as Private 14773 14774 14775@quotation 14776 14777"@cite{Address} should be of a private type." 14778@end quotation 14779 14780Followed. 14781 14782@geindex Operations 14783@geindex on `@w{`}Address`@w{`} 14784 14785@geindex Address 14786@geindex operations of 14787 14788@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14789@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{232} 14790@section RM 13.7.1(16): Address Operations 14791 14792 14793@quotation 14794 14795"Operations in @code{System} and its children should reflect the target 14796environment semantics as closely as is reasonable. For example, on most 14797machines, it makes sense for address arithmetic to 'wrap around'. 14798Operations that do not make sense should raise @code{Program_Error}." 14799@end quotation 14800 14801Followed. Address arithmetic is modular arithmetic that wraps around. No 14802operation raises @code{Program_Error}, since all operations make sense. 14803 14804@geindex Unchecked conversion 14805 14806@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 14807@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{233} 14808@section RM 13.9(14-17): Unchecked Conversion 14809 14810 14811@quotation 14812 14813"The @code{Size} of an array object should not include its bounds; hence, 14814the bounds should not be part of the converted data." 14815@end quotation 14816 14817Followed. 14818 14819@quotation 14820 14821"The implementation should not generate unnecessary run-time checks to 14822ensure that the representation of @code{S} is a representation of the 14823target type. It should take advantage of the permission to return by 14824reference when possible. Restrictions on unchecked conversions should be 14825avoided unless required by the target environment." 14826@end quotation 14827 14828Followed. There are no restrictions on unchecked conversion. A warning is 14829generated if the source and target types do not have the same size since 14830the semantics in this case may be target dependent. 14831 14832@quotation 14833 14834"The recommended level of support for unchecked conversions is: 14835 14836Unchecked conversions should be supported and should be reversible in 14837the cases where this clause defines the result. To enable meaningful use 14838of unchecked conversion, a contiguous representation should be used for 14839elementary subtypes, for statically constrained array subtypes whose 14840component subtype is one of the subtypes described in this paragraph, 14841and for record subtypes without discriminants whose component subtypes 14842are described in this paragraph." 14843@end quotation 14844 14845Followed. 14846 14847@geindex Heap usage 14848@geindex implicit 14849 14850@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 14851@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{234} 14852@section RM 13.11(23-25): Implicit Heap Usage 14853 14854 14855@quotation 14856 14857"An implementation should document any cases in which it dynamically 14858allocates heap storage for a purpose other than the evaluation of an 14859allocator." 14860@end quotation 14861 14862Followed, the only other points at which heap storage is dynamically 14863allocated are as follows: 14864 14865 14866@itemize * 14867 14868@item 14869At initial elaboration time, to allocate dynamically sized global 14870objects. 14871 14872@item 14873To allocate space for a task when a task is created. 14874 14875@item 14876To extend the secondary stack dynamically when needed. The secondary 14877stack is used for returning variable length results. 14878@end itemize 14879 14880 14881@quotation 14882 14883"A default (implementation-provided) storage pool for an 14884access-to-constant type should not have overhead to support deallocation of 14885individual objects." 14886@end quotation 14887 14888Followed. 14889 14890@quotation 14891 14892"A storage pool for an anonymous access type should be created at the 14893point of an allocator for the type, and be reclaimed when the designated 14894object becomes inaccessible." 14895@end quotation 14896 14897Followed. 14898 14899@geindex Unchecked deallocation 14900 14901@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice 14902@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{235} 14903@section RM 13.11.2(17): Unchecked Deallocation 14904 14905 14906@quotation 14907 14908"For a standard storage pool, @code{Free} should actually reclaim the 14909storage." 14910@end quotation 14911 14912Followed. 14913 14914@geindex Stream oriented attributes 14915 14916@node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice 14917@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{236} 14918@section RM 13.13.2(1.6): Stream Oriented Attributes 14919 14920 14921@quotation 14922 14923"If not specified, the value of Stream_Size for an elementary type 14924should be the number of bits that corresponds to the minimum number of 14925stream elements required by the first subtype of the type, rounded up 14926to the nearest factor or multiple of the word size that is also a 14927multiple of the stream element size." 14928@end quotation 14929 14930Followed, except that the number of stream elements is a power of 2. 14931The Stream_Size may be used to override the default choice. 14932 14933However, such an implementation is based on direct binary 14934representations and is therefore target- and endianness-dependent. To 14935address this issue, GNAT also supplies an alternate implementation of 14936the stream attributes @code{Read} and @code{Write}, which uses the 14937target-independent XDR standard representation for scalar types. 14938 14939@geindex XDR representation 14940 14941@geindex Read attribute 14942 14943@geindex Write attribute 14944 14945@geindex Stream oriented attributes 14946 14947The XDR implementation is provided as an alternative body of the 14948@code{System.Stream_Attributes} package, in the file 14949@code{s-stratt-xdr.adb} in the GNAT library. 14950There is no @code{s-stratt-xdr.ads} file. 14951In order to install the XDR implementation, do the following: 14952 14953 14954@itemize * 14955 14956@item 14957Replace the default implementation of the 14958@code{System.Stream_Attributes} package with the XDR implementation. 14959For example on a Unix platform issue the commands: 14960 14961@example 14962$ mv s-stratt.adb s-stratt-default.adb 14963$ mv s-stratt-xdr.adb s-stratt.adb 14964@end example 14965 14966@item 14967Rebuild the GNAT run-time library as documented in 14968the @emph{GNAT and Libraries} section of the @cite{GNAT User's Guide}. 14969@end itemize 14970 14971@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice 14972@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{237} 14973@section RM A.1(52): Names of Predefined Numeric Types 14974 14975 14976@quotation 14977 14978"If an implementation provides additional named predefined integer types, 14979then the names should end with @code{Integer} as in 14980@code{Long_Integer}. If an implementation provides additional named 14981predefined floating point types, then the names should end with 14982@code{Float} as in @code{Long_Float}." 14983@end quotation 14984 14985Followed. 14986 14987@geindex Ada.Characters.Handling 14988 14989@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 14990@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{238} 14991@section RM A.3.2(49): @code{Ada.Characters.Handling} 14992 14993 14994@quotation 14995 14996"If an implementation provides a localized definition of @code{Character} 14997or @code{Wide_Character}, then the effects of the subprograms in 14998@code{Characters.Handling} should reflect the localizations. 14999See also 3.5.2." 15000@end quotation 15001 15002Followed. GNAT provides no such localized definitions. 15003 15004@geindex Bounded-length strings 15005 15006@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 15007@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{239} 15008@section RM A.4.4(106): Bounded-Length String Handling 15009 15010 15011@quotation 15012 15013"Bounded string objects should not be implemented by implicit pointers 15014and dynamic allocation." 15015@end quotation 15016 15017Followed. No implicit pointers or dynamic allocation are used. 15018 15019@geindex Random number generation 15020 15021@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 15022@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23a} 15023@section RM A.5.2(46-47): Random Number Generation 15024 15025 15026@quotation 15027 15028"Any storage associated with an object of type @code{Generator} should be 15029reclaimed on exit from the scope of the object." 15030@end quotation 15031 15032Followed. 15033 15034@quotation 15035 15036"If the generator period is sufficiently long in relation to the number 15037of distinct initiator values, then each possible value of 15038@code{Initiator} passed to @code{Reset} should initiate a sequence of 15039random numbers that does not, in a practical sense, overlap the sequence 15040initiated by any other value. If this is not possible, then the mapping 15041between initiator values and generator states should be a rapidly 15042varying function of the initiator value." 15043@end quotation 15044 15045Followed. The generator period is sufficiently long for the first 15046condition here to hold true. 15047 15048@geindex Get_Immediate 15049 15050@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 15051@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23b} 15052@section RM A.10.7(23): @code{Get_Immediate} 15053 15054 15055@quotation 15056 15057"The @code{Get_Immediate} procedures should be implemented with 15058unbuffered input. For a device such as a keyboard, input should be 15059available if a key has already been typed, whereas for a disk 15060file, input should always be available except at end of file. For a file 15061associated with a keyboard-like device, any line-editing features of the 15062underlying operating system should be disabled during the execution of 15063@code{Get_Immediate}." 15064@end quotation 15065 15066Followed on all targets except VxWorks. For VxWorks, there is no way to 15067provide this functionality that does not result in the input buffer being 15068flushed before the @code{Get_Immediate} call. A special unit 15069@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 15070this functionality. 15071 15072@geindex Export 15073 15074@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice 15075@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23c} 15076@section RM B.1(39-41): Pragma @code{Export} 15077 15078 15079@quotation 15080 15081"If an implementation supports pragma @code{Export} to a given language, 15082then it should also allow the main subprogram to be written in that 15083language. It should support some mechanism for invoking the elaboration 15084of the Ada library units included in the system, and for invoking the 15085finalization of the environment task. On typical systems, the 15086recommended mechanism is to provide two subprograms whose link names are 15087@code{adainit} and @code{adafinal}. @code{adainit} should contain the 15088elaboration code for library units. @code{adafinal} should contain the 15089finalization code. These subprograms should have no effect the second 15090and subsequent time they are called." 15091@end quotation 15092 15093Followed. 15094 15095@quotation 15096 15097"Automatic elaboration of pre-elaborated packages should be 15098provided when pragma @code{Export} is supported." 15099@end quotation 15100 15101Followed when the main program is in Ada. If the main program is in a 15102foreign language, then 15103@code{adainit} must be called to elaborate pre-elaborated 15104packages. 15105 15106@quotation 15107 15108"For each supported convention @emph{L} other than @code{Intrinsic}, an 15109implementation should support @code{Import} and @code{Export} pragmas 15110for objects of @emph{L}-compatible types and for subprograms, and pragma 15111@cite{Convention} for @emph{L}-eligible types and for subprograms, 15112presuming the other language has corresponding features. Pragma 15113@code{Convention} need not be supported for scalar types." 15114@end quotation 15115 15116Followed. 15117 15118@geindex Package Interfaces 15119 15120@geindex Interfaces 15121 15122@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 15123@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{23d} 15124@section RM B.2(12-13): Package @code{Interfaces} 15125 15126 15127@quotation 15128 15129"For each implementation-defined convention identifier, there should be a 15130child package of package Interfaces with the corresponding name. This 15131package should contain any declarations that would be useful for 15132interfacing to the language (implementation) represented by the 15133convention. Any declarations useful for interfacing to any language on 15134the given hardware architecture should be provided directly in 15135@code{Interfaces}." 15136@end quotation 15137 15138Followed. 15139 15140@quotation 15141 15142"An implementation supporting an interface to C, COBOL, or Fortran should 15143provide the corresponding package or packages described in the following 15144clauses." 15145@end quotation 15146 15147Followed. GNAT provides all the packages described in this section. 15148 15149@geindex C 15150@geindex interfacing with 15151 15152@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 15153@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{23e} 15154@section RM B.3(63-71): Interfacing with C 15155 15156 15157@quotation 15158 15159"An implementation should support the following interface correspondences 15160between Ada and C." 15161@end quotation 15162 15163Followed. 15164 15165@quotation 15166 15167"An Ada procedure corresponds to a void-returning C function." 15168@end quotation 15169 15170Followed. 15171 15172@quotation 15173 15174"An Ada function corresponds to a non-void C function." 15175@end quotation 15176 15177Followed. 15178 15179@quotation 15180 15181"An Ada @code{in} scalar parameter is passed as a scalar argument to a C 15182function." 15183@end quotation 15184 15185Followed. 15186 15187@quotation 15188 15189"An Ada @code{in} parameter of an access-to-object type with designated 15190type @code{T} is passed as a @code{t*} argument to a C function, 15191where @code{t} is the C type corresponding to the Ada type @code{T}." 15192@end quotation 15193 15194Followed. 15195 15196@quotation 15197 15198"An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} 15199parameter of an elementary type @code{T}, is passed as a @code{t*} 15200argument to a C function, where @code{t} is the C type corresponding to 15201the Ada type @code{T}. In the case of an elementary @code{out} or 15202@code{in out} parameter, a pointer to a temporary copy is used to 15203preserve by-copy semantics." 15204@end quotation 15205 15206Followed. 15207 15208@quotation 15209 15210"An Ada parameter of a record type @code{T}, of any mode, is passed as a 15211@code{t*} argument to a C function, where @code{t} is the C 15212structure corresponding to the Ada type @code{T}." 15213@end quotation 15214 15215Followed. This convention may be overridden by the use of the C_Pass_By_Copy 15216pragma, or Convention, or by explicitly specifying the mechanism for a given 15217call using an extended import or export pragma. 15218 15219@quotation 15220 15221"An Ada parameter of an array type with component type @code{T}, of any 15222mode, is passed as a @code{t*} argument to a C function, where 15223@code{t} is the C type corresponding to the Ada type @code{T}." 15224@end quotation 15225 15226Followed. 15227 15228@quotation 15229 15230"An Ada parameter of an access-to-subprogram type is passed as a pointer 15231to a C function whose prototype corresponds to the designated 15232subprogram's specification." 15233@end quotation 15234 15235Followed. 15236 15237@geindex COBOL 15238@geindex interfacing with 15239 15240@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 15241@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{23f} 15242@section RM B.4(95-98): Interfacing with COBOL 15243 15244 15245@quotation 15246 15247"An Ada implementation should support the following interface 15248correspondences between Ada and COBOL." 15249@end quotation 15250 15251Followed. 15252 15253@quotation 15254 15255"An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of 15256the COBOL type corresponding to @code{T}." 15257@end quotation 15258 15259Followed. 15260 15261@quotation 15262 15263"An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 15264the corresponding COBOL type." 15265@end quotation 15266 15267Followed. 15268 15269@quotation 15270 15271"Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 15272COBOL type corresponding to the Ada parameter type; for scalars, a local 15273copy is used if necessary to ensure by-copy semantics." 15274@end quotation 15275 15276Followed. 15277 15278@geindex Fortran 15279@geindex interfacing with 15280 15281@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 15282@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{240} 15283@section RM B.5(22-26): Interfacing with Fortran 15284 15285 15286@quotation 15287 15288"An Ada implementation should support the following interface 15289correspondences between Ada and Fortran:" 15290@end quotation 15291 15292Followed. 15293 15294@quotation 15295 15296"An Ada procedure corresponds to a Fortran subroutine." 15297@end quotation 15298 15299Followed. 15300 15301@quotation 15302 15303"An Ada function corresponds to a Fortran function." 15304@end quotation 15305 15306Followed. 15307 15308@quotation 15309 15310"An Ada parameter of an elementary, array, or record type @code{T} is 15311passed as a @code{T} argument to a Fortran procedure, where @code{T} is 15312the Fortran type corresponding to the Ada type @code{T}, and where the 15313INTENT attribute of the corresponding dummy argument matches the Ada 15314formal parameter mode; the Fortran implementation's parameter passing 15315conventions are used. For elementary types, a local copy is used if 15316necessary to ensure by-copy semantics." 15317@end quotation 15318 15319Followed. 15320 15321@quotation 15322 15323"An Ada parameter of an access-to-subprogram type is passed as a 15324reference to a Fortran procedure whose interface corresponds to the 15325designated subprogram's specification." 15326@end quotation 15327 15328Followed. 15329 15330@geindex Machine operations 15331 15332@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 15333@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{241} 15334@section RM C.1(3-5): Access to Machine Operations 15335 15336 15337@quotation 15338 15339"The machine code or intrinsic support should allow access to all 15340operations normally available to assembly language programmers for the 15341target environment, including privileged instructions, if any." 15342@end quotation 15343 15344Followed. 15345 15346@quotation 15347 15348"The interfacing pragmas (see Annex B) should support interface to 15349assembler; the default assembler should be associated with the 15350convention identifier @code{Assembler}." 15351@end quotation 15352 15353Followed. 15354 15355@quotation 15356 15357"If an entity is exported to assembly language, then the implementation 15358should allocate it at an addressable location, and should ensure that it 15359is retained by the linking process, even if not otherwise referenced 15360from the Ada code. The implementation should assume that any call to a 15361machine code or assembler subprogram is allowed to read or update every 15362object that is specified as exported." 15363@end quotation 15364 15365Followed. 15366 15367@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 15368@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{242} 15369@section RM C.1(10-16): Access to Machine Operations 15370 15371 15372@quotation 15373 15374"The implementation should ensure that little or no overhead is 15375associated with calling intrinsic and machine-code subprograms." 15376@end quotation 15377 15378Followed for both intrinsics and machine-code subprograms. 15379 15380@quotation 15381 15382"It is recommended that intrinsic subprograms be provided for convenient 15383access to any machine operations that provide special capabilities or 15384efficiency and that are not otherwise available through the language 15385constructs." 15386@end quotation 15387 15388Followed. A full set of machine operation intrinsic subprograms is provided. 15389 15390@quotation 15391 15392"Atomic read-modify-write operations---e.g., test and set, compare and 15393swap, decrement and test, enqueue/dequeue." 15394@end quotation 15395 15396Followed on any target supporting such operations. 15397 15398@quotation 15399 15400"Standard numeric functions---e.g.:, sin, log." 15401@end quotation 15402 15403Followed on any target supporting such operations. 15404 15405@quotation 15406 15407"String manipulation operations---e.g.:, translate and test." 15408@end quotation 15409 15410Followed on any target supporting such operations. 15411 15412@quotation 15413 15414"Vector operations---e.g.:, compare vector against thresholds." 15415@end quotation 15416 15417Followed on any target supporting such operations. 15418 15419@quotation 15420 15421"Direct operations on I/O ports." 15422@end quotation 15423 15424Followed on any target supporting such operations. 15425 15426@geindex Interrupt support 15427 15428@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 15429@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{243} 15430@section RM C.3(28): Interrupt Support 15431 15432 15433@quotation 15434 15435"If the @code{Ceiling_Locking} policy is not in effect, the 15436implementation should provide means for the application to specify which 15437interrupts are to be blocked during protected actions, if the underlying 15438system allows for a finer-grain control of interrupt blocking." 15439@end quotation 15440 15441Followed. The underlying system does not allow for finer-grain control 15442of interrupt blocking. 15443 15444@geindex Protected procedure handlers 15445 15446@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 15447@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{244} 15448@section RM C.3.1(20-21): Protected Procedure Handlers 15449 15450 15451@quotation 15452 15453"Whenever possible, the implementation should allow interrupt handlers to 15454be called directly by the hardware." 15455@end quotation 15456 15457Followed on any target where the underlying operating system permits 15458such direct calls. 15459 15460@quotation 15461 15462"Whenever practical, violations of any 15463implementation-defined restrictions should be detected before run time." 15464@end quotation 15465 15466Followed. Compile time warnings are given when possible. 15467 15468@geindex Package `@w{`}Interrupts`@w{`} 15469 15470@geindex Interrupts 15471 15472@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 15473@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{245} 15474@section RM C.3.2(25): Package @code{Interrupts} 15475 15476 15477@quotation 15478 15479"If implementation-defined forms of interrupt handler procedures are 15480supported, such as protected procedures with parameters, then for each 15481such form of a handler, a type analogous to @code{Parameterless_Handler} 15482should be specified in a child package of @code{Interrupts}, with the 15483same operations as in the predefined package Interrupts." 15484@end quotation 15485 15486Followed. 15487 15488@geindex Pre-elaboration requirements 15489 15490@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 15491@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{246} 15492@section RM C.4(14): Pre-elaboration Requirements 15493 15494 15495@quotation 15496 15497"It is recommended that pre-elaborated packages be implemented in such a 15498way that there should be little or no code executed at run time for the 15499elaboration of entities not already covered by the Implementation 15500Requirements." 15501@end quotation 15502 15503Followed. Executable code is generated in some cases, e.g., loops 15504to initialize large arrays. 15505 15506@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 15507@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{247} 15508@section RM C.5(8): Pragma @code{Discard_Names} 15509 15510 15511@quotation 15512 15513"If the pragma applies to an entity, then the implementation should 15514reduce the amount of storage used for storing names associated with that 15515entity." 15516@end quotation 15517 15518Followed. 15519 15520@geindex Package Task_Attributes 15521 15522@geindex Task_Attributes 15523 15524@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 15525@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{248} 15526@section RM C.7.2(30): The Package Task_Attributes 15527 15528 15529@quotation 15530 15531"Some implementations are targeted to domains in which memory use at run 15532time must be completely deterministic. For such implementations, it is 15533recommended that the storage for task attributes will be pre-allocated 15534statically and not from the heap. This can be accomplished by either 15535placing restrictions on the number and the size of the task's 15536attributes, or by using the pre-allocated storage for the first @code{N} 15537attribute objects, and the heap for the others. In the latter case, 15538@code{N} should be documented." 15539@end quotation 15540 15541Not followed. This implementation is not targeted to such a domain. 15542 15543@geindex Locking Policies 15544 15545@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 15546@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{249} 15547@section RM D.3(17): Locking Policies 15548 15549 15550@quotation 15551 15552"The implementation should use names that end with @code{_Locking} for 15553locking policies defined by the implementation." 15554@end quotation 15555 15556Followed. Two implementation-defined locking policies are defined, 15557whose names (@code{Inheritance_Locking} and 15558@code{Concurrent_Readers_Locking}) follow this suggestion. 15559 15560@geindex Entry queuing policies 15561 15562@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 15563@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24a} 15564@section RM D.4(16): Entry Queuing Policies 15565 15566 15567@quotation 15568 15569"Names that end with @code{_Queuing} should be used 15570for all implementation-defined queuing policies." 15571@end quotation 15572 15573Followed. No such implementation-defined queuing policies exist. 15574 15575@geindex Preemptive abort 15576 15577@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 15578@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24b} 15579@section RM D.6(9-10): Preemptive Abort 15580 15581 15582@quotation 15583 15584"Even though the @emph{abort_statement} is included in the list of 15585potentially blocking operations (see 9.5.1), it is recommended that this 15586statement be implemented in a way that never requires the task executing 15587the @emph{abort_statement} to block." 15588@end quotation 15589 15590Followed. 15591 15592@quotation 15593 15594"On a multi-processor, the delay associated with aborting a task on 15595another processor should be bounded; the implementation should use 15596periodic polling, if necessary, to achieve this." 15597@end quotation 15598 15599Followed. 15600 15601@geindex Tasking restrictions 15602 15603@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 15604@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24c} 15605@section RM D.7(21): Tasking Restrictions 15606 15607 15608@quotation 15609 15610"When feasible, the implementation should take advantage of the specified 15611restrictions to produce a more efficient implementation." 15612@end quotation 15613 15614GNAT currently takes advantage of these restrictions by providing an optimized 15615run time when the Ravenscar profile and the GNAT restricted run time set 15616of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 15617pragma @code{Profile (Restricted)} for more details. 15618 15619@geindex Time 15620@geindex monotonic 15621 15622@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 15623@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{24d} 15624@section RM D.8(47-49): Monotonic Time 15625 15626 15627@quotation 15628 15629"When appropriate, implementations should provide configuration 15630mechanisms to change the value of @code{Tick}." 15631@end quotation 15632 15633Such configuration mechanisms are not appropriate to this implementation 15634and are thus not supported. 15635 15636@quotation 15637 15638"It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 15639be implemented as transformations of the same time base." 15640@end quotation 15641 15642Followed. 15643 15644@quotation 15645 15646"It is recommended that the best time base which exists in 15647the underlying system be available to the application through 15648@code{Clock}. @cite{Best} may mean highest accuracy or largest range." 15649@end quotation 15650 15651Followed. 15652 15653@geindex Partition communication subsystem 15654 15655@geindex PCS 15656 15657@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 15658@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{24e} 15659@section RM E.5(28-29): Partition Communication Subsystem 15660 15661 15662@quotation 15663 15664"Whenever possible, the PCS on the called partition should allow for 15665multiple tasks to call the RPC-receiver with different messages and 15666should allow them to block until the corresponding subprogram body 15667returns." 15668@end quotation 15669 15670Followed by GLADE, a separately supplied PCS that can be used with 15671GNAT. 15672 15673@quotation 15674 15675"The @code{Write} operation on a stream of type @code{Params_Stream_Type} 15676should raise @code{Storage_Error} if it runs out of space trying to 15677write the @code{Item} into the stream." 15678@end quotation 15679 15680Followed by GLADE, a separately supplied PCS that can be used with 15681GNAT. 15682 15683@geindex COBOL support 15684 15685@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 15686@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{24f} 15687@section RM F(7): COBOL Support 15688 15689 15690@quotation 15691 15692"If COBOL (respectively, C) is widely supported in the target 15693environment, implementations supporting the Information Systems Annex 15694should provide the child package @code{Interfaces.COBOL} (respectively, 15695@code{Interfaces.C}) specified in Annex B and should support a 15696@code{convention_identifier} of COBOL (respectively, C) in the interfacing 15697pragmas (see Annex B), thus allowing Ada programs to interface with 15698programs written in that language." 15699@end quotation 15700 15701Followed. 15702 15703@geindex Decimal radix support 15704 15705@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 15706@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{250} 15707@section RM F.1(2): Decimal Radix Support 15708 15709 15710@quotation 15711 15712"Packed decimal should be used as the internal representation for objects 15713of subtype @code{S} when @code{S}'Machine_Radix = 10." 15714@end quotation 15715 15716Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary 15717representations. 15718 15719@geindex Numerics 15720 15721@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 15722@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{251} 15723@section RM G: Numerics 15724 15725 15726@quotation 15727 15728"If Fortran (respectively, C) is widely supported in the target 15729environment, implementations supporting the Numerics Annex 15730should provide the child package @code{Interfaces.Fortran} (respectively, 15731@code{Interfaces.C}) specified in Annex B and should support a 15732@code{convention_identifier} of Fortran (respectively, C) in the interfacing 15733pragmas (see Annex B), thus allowing Ada programs to interface with 15734programs written in that language." 15735@end quotation 15736 15737Followed. 15738 15739@geindex Complex types 15740 15741@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15742@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{252} 15743@section RM G.1.1(56-58): Complex Types 15744 15745 15746@quotation 15747 15748"Because the usual mathematical meaning of multiplication of a complex 15749operand and a real operand is that of the scaling of both components of 15750the former by the latter, an implementation should not perform this 15751operation by first promoting the real operand to complex type and then 15752performing a full complex multiplication. In systems that, in the 15753future, support an Ada binding to IEC 559:1989, the latter technique 15754will not generate the required result when one of the components of the 15755complex operand is infinite. (Explicit multiplication of the infinite 15756component by the zero component obtained during promotion yields a NaN 15757that propagates into the final result.) Analogous advice applies in the 15758case of multiplication of a complex operand and a pure-imaginary 15759operand, and in the case of division of a complex operand by a real or 15760pure-imaginary operand." 15761@end quotation 15762 15763Not followed. 15764 15765@quotation 15766 15767"Similarly, because the usual mathematical meaning of addition of a 15768complex operand and a real operand is that the imaginary operand remains 15769unchanged, an implementation should not perform this operation by first 15770promoting the real operand to complex type and then performing a full 15771complex addition. In implementations in which the @code{Signed_Zeros} 15772attribute of the component type is @code{True} (and which therefore 15773conform to IEC 559:1989 in regard to the handling of the sign of zero in 15774predefined arithmetic operations), the latter technique will not 15775generate the required result when the imaginary component of the complex 15776operand is a negatively signed zero. (Explicit addition of the negative 15777zero to the zero obtained during promotion yields a positive zero.) 15778Analogous advice applies in the case of addition of a complex operand 15779and a pure-imaginary operand, and in the case of subtraction of a 15780complex operand and a real or pure-imaginary operand." 15781@end quotation 15782 15783Not followed. 15784 15785@quotation 15786 15787"Implementations in which @code{Real'Signed_Zeros} is @code{True} should 15788attempt to provide a rational treatment of the signs of zero results and 15789result components. As one example, the result of the @code{Argument} 15790function should have the sign of the imaginary component of the 15791parameter @code{X} when the point represented by that parameter lies on 15792the positive real axis; as another, the sign of the imaginary component 15793of the @code{Compose_From_Polar} function should be the same as 15794(respectively, the opposite of) that of the @code{Argument} parameter when that 15795parameter has a value of zero and the @code{Modulus} parameter has a 15796nonnegative (respectively, negative) value." 15797@end quotation 15798 15799Followed. 15800 15801@geindex Complex elementary functions 15802 15803@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 15804@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{253} 15805@section RM G.1.2(49): Complex Elementary Functions 15806 15807 15808@quotation 15809 15810"Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 15811@code{True} should attempt to provide a rational treatment of the signs 15812of zero results and result components. For example, many of the complex 15813elementary functions have components that are odd functions of one of 15814the parameter components; in these cases, the result component should 15815have the sign of the parameter component at the origin. Other complex 15816elementary functions have zero components whose sign is opposite that of 15817a parameter component at the origin, or is always positive or always 15818negative." 15819@end quotation 15820 15821Followed. 15822 15823@geindex Accuracy requirements 15824 15825@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 15826@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{254} 15827@section RM G.2.4(19): Accuracy Requirements 15828 15829 15830@quotation 15831 15832"The versions of the forward trigonometric functions without a 15833@code{Cycle} parameter should not be implemented by calling the 15834corresponding version with a @code{Cycle} parameter of 15835@code{2.0*Numerics.Pi}, since this will not provide the required 15836accuracy in some portions of the domain. For the same reason, the 15837version of @code{Log} without a @code{Base} parameter should not be 15838implemented by calling the corresponding version with a @code{Base} 15839parameter of @code{Numerics.e}." 15840@end quotation 15841 15842Followed. 15843 15844@geindex Complex arithmetic accuracy 15845 15846@geindex Accuracy 15847@geindex complex arithmetic 15848 15849@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 15850@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{255} 15851@section RM G.2.6(15): Complex Arithmetic Accuracy 15852 15853 15854@quotation 15855 15856"The version of the @code{Compose_From_Polar} function without a 15857@code{Cycle} parameter should not be implemented by calling the 15858corresponding version with a @code{Cycle} parameter of 15859@code{2.0*Numerics.Pi}, since this will not provide the required 15860accuracy in some portions of the domain." 15861@end quotation 15862 15863Followed. 15864 15865@geindex Sequential elaboration policy 15866 15867@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15868@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{256} 15869@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15870 15871 15872@quotation 15873 15874"If the partition elaboration policy is @code{Sequential} and the 15875Environment task becomes permanently blocked during elaboration then the 15876partition is deadlocked and it is recommended that the partition be 15877immediately terminated." 15878@end quotation 15879 15880Not followed. 15881 15882@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15883@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{257}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{258} 15884@chapter Implementation Defined Characteristics 15885 15886 15887In addition to the implementation dependent pragmas and attributes, and the 15888implementation advice, there are a number of other Ada features that are 15889potentially implementation dependent and are designated as 15890implementation-defined. These are mentioned throughout the Ada Reference 15891Manual, and are summarized in Annex M. 15892 15893A requirement for conforming Ada compilers is that they provide 15894documentation describing how the implementation deals with each of these 15895issues. In this chapter you will find each point in Annex M listed, 15896followed by a description of how GNAT 15897handles the implementation dependence. 15898 15899You can use this chapter as a guide to minimizing implementation 15900dependent features in your programs if portability to other compilers 15901and other operating systems is an important consideration. The numbers 15902in each entry below correspond to the paragraph numbers in the Ada 15903Reference Manual. 15904 15905 15906@itemize * 15907 15908@item 15909"Whether or not each recommendation given in Implementation 15910Advice is followed. See 1.1.2(37)." 15911@end itemize 15912 15913See @ref{a,,Implementation Advice}. 15914 15915 15916@itemize * 15917 15918@item 15919"Capacity limitations of the implementation. See 1.1.3(3)." 15920@end itemize 15921 15922The complexity of programs that can be processed is limited only by the 15923total amount of available virtual memory, and disk space for the 15924generated object files. 15925 15926 15927@itemize * 15928 15929@item 15930"Variations from the standard that are impractical to avoid 15931given the implementation's execution environment. See 1.1.3(6)." 15932@end itemize 15933 15934There are no variations from the standard. 15935 15936 15937@itemize * 15938 15939@item 15940"Which code_statements cause external 15941interactions. See 1.1.3(10)." 15942@end itemize 15943 15944Any @emph{code_statement} can potentially cause external interactions. 15945 15946 15947@itemize * 15948 15949@item 15950"The coded representation for the text of an Ada 15951program. See 2.1(4)." 15952@end itemize 15953 15954See separate section on source representation. 15955 15956 15957@itemize * 15958 15959@item 15960"The control functions allowed in comments. See 2.1(14)." 15961@end itemize 15962 15963See separate section on source representation. 15964 15965 15966@itemize * 15967 15968@item 15969"The representation for an end of line. See 2.2(2)." 15970@end itemize 15971 15972See separate section on source representation. 15973 15974 15975@itemize * 15976 15977@item 15978"Maximum supported line length and lexical element 15979length. See 2.2(15)." 15980@end itemize 15981 15982The maximum line length is 255 characters and the maximum length of 15983a lexical element is also 255 characters. This is the default setting 15984if not overridden by the use of compiler switch @emph{-gnaty} (which 15985sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15986line length to be specified to be any value up to 32767. The maximum 15987length of a lexical element is the same as the maximum line length. 15988 15989 15990@itemize * 15991 15992@item 15993"Implementation defined pragmas. See 2.8(14)." 15994@end itemize 15995 15996See @ref{7,,Implementation Defined Pragmas}. 15997 15998 15999@itemize * 16000 16001@item 16002"Effect of pragma @code{Optimize}. See 2.8(27)." 16003@end itemize 16004 16005Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 16006parameter, checks that the optimization flag is set, and aborts if it is 16007not. 16008 16009 16010@itemize * 16011 16012@item 16013"The sequence of characters of the value returned by 16014@code{S'Image} when some of the graphic characters of 16015@code{S'Wide_Image} are not defined in @code{Character}. See 160163.5(37)." 16017@end itemize 16018 16019The sequence of characters is as defined by the wide character encoding 16020method used for the source. See section on source representation for 16021further details. 16022 16023 16024@itemize * 16025 16026@item 16027"The predefined integer types declared in 16028@code{Standard}. See 3.5.4(25)." 16029@end itemize 16030 16031 16032@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16033@headitem 16034 16035Type 16036 16037@tab 16038 16039Representation 16040 16041@item 16042 16043@emph{Short_Short_Integer} 16044 16045@tab 16046 160478 bit signed 16048 16049@item 16050 16051@emph{Short_Integer} 16052 16053@tab 16054 16055(Short) 16 bit signed 16056 16057@item 16058 16059@emph{Integer} 16060 16061@tab 16062 1606332 bit signed 16064 16065@item 16066 16067@emph{Long_Integer} 16068 16069@tab 16070 1607164 bit signed (on most 64 bit targets, 16072depending on the C definition of long). 1607332 bit signed (all other targets) 16074 16075@item 16076 16077@emph{Long_Long_Integer} 16078 16079@tab 16080 1608164 bit signed 16082 16083@end multitable 16084 16085 16086 16087@itemize * 16088 16089@item 16090"Any nonstandard integer types and the operators defined 16091for them. See 3.5.4(26)." 16092@end itemize 16093 16094There are no nonstandard integer types. 16095 16096 16097@itemize * 16098 16099@item 16100"Any nonstandard real types and the operators defined for 16101them. See 3.5.6(8)." 16102@end itemize 16103 16104There are no nonstandard real types. 16105 16106 16107@itemize * 16108 16109@item 16110"What combinations of requested decimal precision and range 16111are supported for floating point types. See 3.5.7(7)." 16112@end itemize 16113 16114The precision and range is as defined by the IEEE standard. 16115 16116 16117@itemize * 16118 16119@item 16120"The predefined floating point types declared in 16121@code{Standard}. See 3.5.7(16)." 16122@end itemize 16123 16124 16125@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16126@headitem 16127 16128Type 16129 16130@tab 16131 16132Representation 16133 16134@item 16135 16136@emph{Short_Float} 16137 16138@tab 16139 1614032 bit IEEE short 16141 16142@item 16143 16144@emph{Float} 16145 16146@tab 16147 16148(Short) 32 bit IEEE short 16149 16150@item 16151 16152@emph{Long_Float} 16153 16154@tab 16155 1615664 bit IEEE long 16157 16158@item 16159 16160@emph{Long_Long_Float} 16161 16162@tab 16163 1616464 bit IEEE long (80 bit IEEE long on x86 processors) 16165 16166@end multitable 16167 16168 16169 16170@itemize * 16171 16172@item 16173"The small of an ordinary fixed point type. See 3.5.9(8)." 16174@end itemize 16175 16176@code{Fine_Delta} is 2**(-63) 16177 16178 16179@itemize * 16180 16181@item 16182"What combinations of small, range, and digits are 16183supported for fixed point types. See 3.5.9(10)." 16184@end itemize 16185 16186Any combinations are permitted that do not result in a small less than 16187@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 16188If the mantissa is larger than 53 bits on machines where Long_Long_Float 16189is 64 bits (true of all architectures except ia32), then the output from 16190Text_IO is accurate to only 53 bits, rather than the full mantissa. This 16191is because floating-point conversions are used to convert fixed point. 16192 16193 16194@itemize * 16195 16196@item 16197"The result of @code{Tags.Expanded_Name} for types declared 16198within an unnamed @emph{block_statement}. See 3.9(10)." 16199@end itemize 16200 16201Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a 16202decimal integer are allocated. 16203 16204 16205@itemize * 16206 16207@item 16208"Implementation-defined attributes. See 4.1.4(12)." 16209@end itemize 16210 16211See @ref{8,,Implementation Defined Attributes}. 16212 16213 16214@itemize * 16215 16216@item 16217"Any implementation-defined time types. See 9.6(6)." 16218@end itemize 16219 16220There are no implementation-defined time types. 16221 16222 16223@itemize * 16224 16225@item 16226"The time base associated with relative delays." 16227@end itemize 16228 16229See 9.6(20). The time base used is that provided by the C library 16230function @code{gettimeofday}. 16231 16232 16233@itemize * 16234 16235@item 16236"The time base of the type @code{Calendar.Time}. See 162379.6(23)." 16238@end itemize 16239 16240The time base used is that provided by the C library function 16241@code{gettimeofday}. 16242 16243 16244@itemize * 16245 16246@item 16247"The time zone used for package @code{Calendar} 16248operations. See 9.6(24)." 16249@end itemize 16250 16251The time zone used by package @code{Calendar} is the current system time zone 16252setting for local time, as accessed by the C library function 16253@code{localtime}. 16254 16255 16256@itemize * 16257 16258@item 16259"Any limit on @emph{delay_until_statements} of 16260@emph{select_statements}. See 9.6(29)." 16261@end itemize 16262 16263There are no such limits. 16264 16265 16266@itemize * 16267 16268@item 16269"Whether or not two non-overlapping parts of a composite 16270object are independently addressable, in the case where packing, record 16271layout, or @code{Component_Size} is specified for the object. See 162729.10(1)." 16273@end itemize 16274 16275Separate components are independently addressable if they do not share 16276overlapping storage units. 16277 16278 16279@itemize * 16280 16281@item 16282"The representation for a compilation. See 10.1(2)." 16283@end itemize 16284 16285A compilation is represented by a sequence of files presented to the 16286compiler in a single invocation of the @emph{gcc} command. 16287 16288 16289@itemize * 16290 16291@item 16292"Any restrictions on compilations that contain multiple 16293compilation_units. See 10.1(4)." 16294@end itemize 16295 16296No single file can contain more than one compilation unit, but any 16297sequence of files can be presented to the compiler as a single 16298compilation. 16299 16300 16301@itemize * 16302 16303@item 16304"The mechanisms for creating an environment and for adding 16305and replacing compilation units. See 10.1.4(3)." 16306@end itemize 16307 16308See separate section on compilation model. 16309 16310 16311@itemize * 16312 16313@item 16314"The manner of explicitly assigning library units to a 16315partition. See 10.2(2)." 16316@end itemize 16317 16318If a unit contains an Ada main program, then the Ada units for the partition 16319are determined by recursive application of the rules in the Ada Reference 16320Manual section 10.2(2-6). In other words, the Ada units will be those that 16321are needed by the main program, and then this definition of need is applied 16322recursively to those units, and the partition contains the transitive 16323closure determined by this relationship. In short, all the necessary units 16324are included, with no need to explicitly specify the list. If additional 16325units are required, e.g., by foreign language units, then all units must be 16326mentioned in the context clause of one of the needed Ada units. 16327 16328If the partition contains no main program, or if the main program is in 16329a language other than Ada, then GNAT 16330provides the binder options @emph{-z} and @emph{-n} respectively, and in 16331this case a list of units can be explicitly supplied to the binder for 16332inclusion in the partition (all units needed by these units will also 16333be included automatically). For full details on the use of these 16334options, refer to @emph{GNAT Make Program gnatmake} in the 16335@cite{GNAT User's Guide}. 16336 16337 16338@itemize * 16339 16340@item 16341"The implementation-defined means, if any, of specifying 16342which compilation units are needed by a given compilation unit. See 1634310.2(2)." 16344@end itemize 16345 16346The units needed by a given compilation unit are as defined in 16347the Ada Reference Manual section 10.2(2-6). There are no 16348implementation-defined pragmas or other implementation-defined 16349means for specifying needed units. 16350 16351 16352@itemize * 16353 16354@item 16355"The manner of designating the main subprogram of a 16356partition. See 10.2(7)." 16357@end itemize 16358 16359The main program is designated by providing the name of the 16360corresponding @code{ALI} file as the input parameter to the binder. 16361 16362 16363@itemize * 16364 16365@item 16366"The order of elaboration of @emph{library_items}. See 1636710.2(18)." 16368@end itemize 16369 16370The first constraint on ordering is that it meets the requirements of 16371Chapter 10 of the Ada Reference Manual. This still leaves some 16372implementation dependent choices, which are resolved by first 16373elaborating bodies as early as possible (i.e., in preference to specs 16374where there is a choice), and second by evaluating the immediate with 16375clauses of a unit to determine the probably best choice, and 16376third by elaborating in alphabetical order of unit names 16377where a choice still remains. 16378 16379 16380@itemize * 16381 16382@item 16383"Parameter passing and function return for the main 16384subprogram. See 10.2(21)." 16385@end itemize 16386 16387The main program has no parameters. It may be a procedure, or a function 16388returning an integer type. In the latter case, the returned integer 16389value is the return code of the program (overriding any value that 16390may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 16391 16392 16393@itemize * 16394 16395@item 16396"The mechanisms for building and running partitions. See 1639710.2(24)." 16398@end itemize 16399 16400GNAT itself supports programs with only a single partition. The GNATDIST 16401tool provided with the GLADE package (which also includes an implementation 16402of the PCS) provides a completely flexible method for building and running 16403programs consisting of multiple partitions. See the separate GLADE manual 16404for details. 16405 16406 16407@itemize * 16408 16409@item 16410"The details of program execution, including program 16411termination. See 10.2(25)." 16412@end itemize 16413 16414See separate section on compilation model. 16415 16416 16417@itemize * 16418 16419@item 16420"The semantics of any non-active partitions supported by the 16421implementation. See 10.2(28)." 16422@end itemize 16423 16424Passive partitions are supported on targets where shared memory is 16425provided by the operating system. See the GLADE reference manual for 16426further details. 16427 16428 16429@itemize * 16430 16431@item 16432"The information returned by @code{Exception_Message}. See 1643311.4.1(10)." 16434@end itemize 16435 16436Exception message returns the null string unless a specific message has 16437been passed by the program. 16438 16439 16440@itemize * 16441 16442@item 16443"The result of @code{Exceptions.Exception_Name} for types 16444declared within an unnamed @emph{block_statement}. See 11.4.1(12)." 16445@end itemize 16446 16447Blocks have implementation defined names of the form @code{B@emph{nnn}} 16448where @emph{nnn} is an integer. 16449 16450 16451@itemize * 16452 16453@item 16454"The information returned by 16455@code{Exception_Information}. See 11.4.1(13)." 16456@end itemize 16457 16458@code{Exception_Information} returns a string in the following format: 16459 16460@example 16461*Exception_Name:* nnnnn 16462*Message:* mmmmm 16463*PID:* ppp 16464*Load address:* 0xhhhh 16465*Call stack traceback locations:* 164660xhhhh 0xhhhh 0xhhhh ... 0xhhh 16467@end example 16468 16469where 16470 16471@quotation 16472 16473 16474@itemize * 16475 16476@item 16477@code{nnnn} is the fully qualified name of the exception in all upper 16478case letters. This line is always present. 16479 16480@item 16481@code{mmmm} is the message (this line present only if message is non-null) 16482 16483@item 16484@code{ppp} is the Process Id value as a decimal integer (this line is 16485present only if the Process Id is nonzero). Currently we are 16486not making use of this field. 16487 16488@item 16489The Load address line, the Call stack traceback locations line and the 16490following values are present only if at least one traceback location was 16491recorded. The Load address indicates the address at which the main executable 16492was loaded; this line may not be present if operating system hasn't relocated 16493the main executable. The values are given in C style format, with lower case 16494letters for a-f, and only as many digits present as are necessary. 16495The line terminator sequence at the end of each line, including 16496the last line is a single @code{LF} character (@code{16#0A#}). 16497@end itemize 16498@end quotation 16499 16500 16501@itemize * 16502 16503@item 16504"Implementation-defined check names. See 11.5(27)." 16505@end itemize 16506 16507The implementation defined check names include Alignment_Check, 16508Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 16509Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 16510program can add implementation-defined check names by means of the pragma 16511Check_Name. See the description of pragma @code{Suppress} for full details. 16512 16513 16514@itemize * 16515 16516@item 16517"The interpretation of each aspect of representation. See 1651813.1(20)." 16519@end itemize 16520 16521See separate section on data representations. 16522 16523 16524@itemize * 16525 16526@item 16527"Any restrictions placed upon representation items. See 1652813.1(20)." 16529@end itemize 16530 16531See separate section on data representations. 16532 16533 16534@itemize * 16535 16536@item 16537"The meaning of @code{Size} for indefinite subtypes. See 1653813.3(48)." 16539@end itemize 16540 16541Size for an indefinite subtype is the maximum possible size, except that 16542for the case of a subprogram parameter, the size of the parameter object 16543is the actual size. 16544 16545 16546@itemize * 16547 16548@item 16549"The default external representation for a type tag. See 1655013.3(75)." 16551@end itemize 16552 16553The default external representation for a type tag is the fully expanded 16554name of the type in upper case letters. 16555 16556 16557@itemize * 16558 16559@item 16560"What determines whether a compilation unit is the same in 16561two different partitions. See 13.3(76)." 16562@end itemize 16563 16564A compilation unit is the same in two different partitions if and only 16565if it derives from the same source file. 16566 16567 16568@itemize * 16569 16570@item 16571"Implementation-defined components. See 13.5.1(15)." 16572@end itemize 16573 16574The only implementation defined component is the tag for a tagged type, 16575which contains a pointer to the dispatching table. 16576 16577 16578@itemize * 16579 16580@item 16581"If @code{Word_Size} = @code{Storage_Unit}, the default bit 16582ordering. See 13.5.3(5)." 16583@end itemize 16584 16585@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 16586implementation, so no non-default bit ordering is supported. The default 16587bit ordering corresponds to the natural endianness of the target architecture. 16588 16589 16590@itemize * 16591 16592@item 16593"The contents of the visible part of package @code{System} 16594and its language-defined children. See 13.7(2)." 16595@end itemize 16596 16597See the definition of these packages in files @code{system.ads} and 16598@code{s-stoele.ads}. Note that two declarations are added to package 16599System. 16600 16601@example 16602Max_Priority : constant Positive := Priority'Last; 16603Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 16604@end example 16605 16606 16607@itemize * 16608 16609@item 16610"The contents of the visible part of package 16611@code{System.Machine_Code}, and the meaning of 16612@emph{code_statements}. See 13.8(7)." 16613@end itemize 16614 16615See the definition and documentation in file @code{s-maccod.ads}. 16616 16617 16618@itemize * 16619 16620@item 16621"The effect of unchecked conversion. See 13.9(11)." 16622@end itemize 16623 16624Unchecked conversion between types of the same size 16625results in an uninterpreted transmission of the bits from one type 16626to the other. If the types are of unequal sizes, then in the case of 16627discrete types, a shorter source is first zero or sign extended as 16628necessary, and a shorter target is simply truncated on the left. 16629For all non-discrete types, the source is first copied if necessary 16630to ensure that the alignment requirements of the target are met, then 16631a pointer is constructed to the source value, and the result is obtained 16632by dereferencing this pointer after converting it to be a pointer to the 16633target type. Unchecked conversions where the target subtype is an 16634unconstrained array are not permitted. If the target alignment is 16635greater than the source alignment, then a copy of the result is 16636made with appropriate alignment 16637 16638 16639@itemize * 16640 16641@item 16642"The semantics of operations on invalid representations. 16643See 13.9.2(10-11)." 16644@end itemize 16645 16646For assignments and other operations where the use of invalid values cannot 16647result in erroneous behavior, the compiler ignores the possibility of invalid 16648values. An exception is raised at the point where an invalid value would 16649result in erroneous behavior. For example executing: 16650 16651@example 16652procedure invalidvals is 16653 X : Integer := -1; 16654 Y : Natural range 1 .. 10; 16655 for Y'Address use X'Address; 16656 Z : Natural range 1 .. 10; 16657 A : array (Natural range 1 .. 10) of Integer; 16658begin 16659 Z := Y; -- no exception 16660 A (Z) := 3; -- exception raised; 16661end; 16662@end example 16663 16664As indicated, an exception is raised on the array assignment, but not 16665on the simple assignment of the invalid negative value from Y to Z. 16666 16667 16668@itemize * 16669 16670@item 16671"The manner of choosing a storage pool for an access type 16672when @code{Storage_Pool} is not specified for the type. See 13.11(17)." 16673@end itemize 16674 16675There are 3 different standard pools used by the compiler when 16676@code{Storage_Pool} is not specified depending whether the type is local 16677to a subprogram or defined at the library level and whether 16678@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime 16679library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and 16680@code{System.Pool_Local} in files @code{s-poosiz.ads}, 16681@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 16682default pools used. 16683 16684 16685@itemize * 16686 16687@item 16688"Whether or not the implementation provides user-accessible 16689names for the standard pool type(s). See 13.11(17)." 16690@end itemize 16691 16692See documentation in the sources of the run time mentioned in the previous 16693paragraph. All these pools are accessible by means of @cite{with}ing 16694these units. 16695 16696 16697@itemize * 16698 16699@item 16700"The meaning of @code{Storage_Size}. See 13.11(18)." 16701@end itemize 16702 16703@code{Storage_Size} is measured in storage units, and refers to the 16704total space available for an access type collection, or to the primary 16705stack space for a task. 16706 16707 16708@itemize * 16709 16710@item 16711"Implementation-defined aspects of storage pools. See 1671213.11(22)." 16713@end itemize 16714 16715See documentation in the sources of the run time mentioned in the 16716paragraph about standard storage pools above 16717for details on GNAT-defined aspects of storage pools. 16718 16719 16720@itemize * 16721 16722@item 16723"The set of restrictions allowed in a pragma 16724@code{Restrictions}. See 13.12(7)." 16725@end itemize 16726 16727See @ref{9,,Standard and Implementation Defined Restrictions}. 16728 16729 16730@itemize * 16731 16732@item 16733"The consequences of violating limitations on 16734@code{Restrictions} pragmas. See 13.12(9)." 16735@end itemize 16736 16737Restrictions that can be checked at compile time result in illegalities 16738if violated. Currently there are no other consequences of violating 16739restrictions. 16740 16741 16742@itemize * 16743 16744@item 16745"The representation used by the @code{Read} and 16746@code{Write} attributes of elementary types in terms of stream 16747elements. See 13.13.2(9)." 16748@end itemize 16749 16750The representation is the in-memory representation of the base type of 16751the type, using the number of bits corresponding to the 16752@code{type'Size} value, and the natural ordering of the machine. 16753 16754 16755@itemize * 16756 16757@item 16758"The names and characteristics of the numeric subtypes 16759declared in the visible part of package @code{Standard}. See A.1(3)." 16760@end itemize 16761 16762See items describing the integer and floating-point types supported. 16763 16764 16765@itemize * 16766 16767@item 16768"The string returned by @code{Character_Set_Version}. 16769See A.3.5(3)." 16770@end itemize 16771 16772@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns 16773the string "Unicode 4.0", referring to version 4.0 of the 16774Unicode specification. 16775 16776 16777@itemize * 16778 16779@item 16780"The accuracy actually achieved by the elementary 16781functions. See A.5.1(1)." 16782@end itemize 16783 16784The elementary functions correspond to the functions available in the C 16785library. Only fast math mode is implemented. 16786 16787 16788@itemize * 16789 16790@item 16791"The sign of a zero result from some of the operators or 16792functions in @code{Numerics.Generic_Elementary_Functions}, when 16793@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)." 16794@end itemize 16795 16796The sign of zeroes follows the requirements of the IEEE 754 standard on 16797floating-point. 16798 16799 16800@itemize * 16801 16802@item 16803"The value of 16804@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)." 16805@end itemize 16806 16807Maximum image width is 6864, see library file @code{s-rannum.ads}. 16808 16809 16810@itemize * 16811 16812@item 16813"The value of 16814@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)." 16815@end itemize 16816 16817Maximum image width is 6864, see library file @code{s-rannum.ads}. 16818 16819 16820@itemize * 16821 16822@item 16823"The algorithms for random number generation. See 16824A.5.2(32)." 16825@end itemize 16826 16827The algorithm is the Mersenne Twister, as documented in the source file 16828@code{s-rannum.adb}. This version of the algorithm has a period of 168292**19937-1. 16830 16831 16832@itemize * 16833 16834@item 16835"The string representation of a random number generator's 16836state. See A.5.2(38)." 16837@end itemize 16838 16839The value returned by the Image function is the concatenation of 16840the fixed-width decimal representations of the 624 32-bit integers 16841of the state vector. 16842 16843 16844@itemize * 16845 16846@item 16847"The minimum time interval between calls to the 16848time-dependent Reset procedure that are guaranteed to initiate different 16849random number sequences. See A.5.2(45)." 16850@end itemize 16851 16852The minimum period between reset calls to guarantee distinct series of 16853random numbers is one microsecond. 16854 16855 16856@itemize * 16857 16858@item 16859"The values of the @code{Model_Mantissa}, 16860@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 16861@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 16862Annex is not supported. See A.5.3(72)." 16863@end itemize 16864 16865Run the compiler with @emph{-gnatS} to produce a listing of package 16866@code{Standard}, has the values of all numeric attributes. 16867 16868 16869@itemize * 16870 16871@item 16872"Any implementation-defined characteristics of the 16873input-output packages. See A.7(14)." 16874@end itemize 16875 16876There are no special implementation defined characteristics for these 16877packages. 16878 16879 16880@itemize * 16881 16882@item 16883"The value of @code{Buffer_Size} in @code{Storage_IO}. See 16884A.9(10)." 16885@end itemize 16886 16887All type representations are contiguous, and the @code{Buffer_Size} is 16888the value of @code{type'Size} rounded up to the next storage unit 16889boundary. 16890 16891 16892@itemize * 16893 16894@item 16895"External files for standard input, standard output, and 16896standard error See A.10(5)." 16897@end itemize 16898 16899These files are mapped onto the files provided by the C streams 16900libraries. See source file @code{i-cstrea.ads} for further details. 16901 16902 16903@itemize * 16904 16905@item 16906"The accuracy of the value produced by @code{Put}. See 16907A.10.9(36)." 16908@end itemize 16909 16910If more digits are requested in the output than are represented by the 16911precision of the value, zeroes are output in the corresponding least 16912significant digit positions. 16913 16914 16915@itemize * 16916 16917@item 16918"The meaning of @code{Argument_Count}, @code{Argument}, and 16919@code{Command_Name}. See A.15(1)." 16920@end itemize 16921 16922These are mapped onto the @code{argv} and @code{argc} parameters of the 16923main program in the natural manner. 16924 16925 16926@itemize * 16927 16928@item 16929"The interpretation of the @code{Form} parameter in procedure 16930@code{Create_Directory}. See A.16(56)." 16931@end itemize 16932 16933The @code{Form} parameter is not used. 16934 16935 16936@itemize * 16937 16938@item 16939"The interpretation of the @code{Form} parameter in procedure 16940@code{Create_Path}. See A.16(60)." 16941@end itemize 16942 16943The @code{Form} parameter is not used. 16944 16945 16946@itemize * 16947 16948@item 16949"The interpretation of the @code{Form} parameter in procedure 16950@code{Copy_File}. See A.16(68)." 16951@end itemize 16952 16953The @code{Form} parameter is case-insensitive. 16954Two fields are recognized in the @code{Form} parameter: 16955 16956@example 16957*preserve=<value>* 16958*mode=<value>* 16959@end example 16960 16961<value> starts immediately after the character '=' and ends with the 16962character immediately preceding the next comma (',') or with the last 16963character of the parameter. 16964 16965The only possible values for preserve= are: 16966 16967 16968@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16969@headitem 16970 16971Value 16972 16973@tab 16974 16975Meaning 16976 16977@item 16978 16979@emph{no_attributes} 16980 16981@tab 16982 16983Do not try to preserve any file attributes. This is the 16984default if no preserve= is found in Form. 16985 16986@item 16987 16988@emph{all_attributes} 16989 16990@tab 16991 16992Try to preserve all file attributes (timestamps, access rights). 16993 16994@item 16995 16996@emph{timestamps} 16997 16998@tab 16999 17000Preserve the timestamp of the copied file, but not the other 17001file attributes. 17002 17003@end multitable 17004 17005 17006The only possible values for mode= are: 17007 17008 17009@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17010@headitem 17011 17012Value 17013 17014@tab 17015 17016Meaning 17017 17018@item 17019 17020@emph{copy} 17021 17022@tab 17023 17024Only do the copy if the destination file does not already exist. 17025If it already exists, Copy_File fails. 17026 17027@item 17028 17029@emph{overwrite} 17030 17031@tab 17032 17033Copy the file in all cases. Overwrite an already existing destination file. 17034 17035@item 17036 17037@emph{append} 17038 17039@tab 17040 17041Append the original file to the destination file. If the destination file 17042does not exist, the destination file is a copy of the source file. 17043When mode=append, the field preserve=, if it exists, is not taken into account. 17044 17045@end multitable 17046 17047 17048If the Form parameter includes one or both of the fields and the value or 17049values are incorrect, Copy_file fails with Use_Error. 17050 17051Examples of correct Forms: 17052 17053@example 17054Form => "preserve=no_attributes,mode=overwrite" (the default) 17055Form => "mode=append" 17056Form => "mode=copy, preserve=all_attributes" 17057@end example 17058 17059Examples of incorrect Forms: 17060 17061@example 17062Form => "preserve=junk" 17063Form => "mode=internal, preserve=timestamps" 17064@end example 17065 17066 17067@itemize * 17068 17069@item 17070"The interpretation of the @code{Pattern} parameter, when not the null string, 17071in the @code{Start_Search} and @code{Search} procedures. 17072See A.16(104) and A.16(112)." 17073@end itemize 17074 17075When the @code{Pattern} parameter is not the null string, it is interpreted 17076according to the syntax of regular expressions as defined in the 17077@code{GNAT.Regexp} package. 17078 17079See @ref{259,,GNAT.Regexp (g-regexp.ads)}. 17080 17081 17082@itemize * 17083 17084@item 17085"Implementation-defined convention names. See B.1(11)." 17086@end itemize 17087 17088The following convention names are supported 17089 17090 17091@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17092@headitem 17093 17094Convention Name 17095 17096@tab 17097 17098Interpretation 17099 17100@item 17101 17102@emph{Ada} 17103 17104@tab 17105 17106Ada 17107 17108@item 17109 17110@emph{Ada_Pass_By_Copy} 17111 17112@tab 17113 17114Allowed for any types except by-reference types such as limited 17115records. Compatible with convention Ada, but causes any parameters 17116with this convention to be passed by copy. 17117 17118@item 17119 17120@emph{Ada_Pass_By_Reference} 17121 17122@tab 17123 17124Allowed for any types except by-copy types such as scalars. 17125Compatible with convention Ada, but causes any parameters 17126with this convention to be passed by reference. 17127 17128@item 17129 17130@emph{Assembler} 17131 17132@tab 17133 17134Assembly language 17135 17136@item 17137 17138@emph{Asm} 17139 17140@tab 17141 17142Synonym for Assembler 17143 17144@item 17145 17146@emph{Assembly} 17147 17148@tab 17149 17150Synonym for Assembler 17151 17152@item 17153 17154@emph{C} 17155 17156@tab 17157 17158C 17159 17160@item 17161 17162@emph{C_Pass_By_Copy} 17163 17164@tab 17165 17166Allowed only for record types, like C, but also notes that record 17167is to be passed by copy rather than reference. 17168 17169@item 17170 17171@emph{COBOL} 17172 17173@tab 17174 17175COBOL 17176 17177@item 17178 17179@emph{C_Plus_Plus (or CPP)} 17180 17181@tab 17182 17183C++ 17184 17185@item 17186 17187@emph{Default} 17188 17189@tab 17190 17191Treated the same as C 17192 17193@item 17194 17195@emph{External} 17196 17197@tab 17198 17199Treated the same as C 17200 17201@item 17202 17203@emph{Fortran} 17204 17205@tab 17206 17207Fortran 17208 17209@item 17210 17211@emph{Intrinsic} 17212 17213@tab 17214 17215For support of pragma @code{Import} with convention Intrinsic, see 17216separate section on Intrinsic Subprograms. 17217 17218@item 17219 17220@emph{Stdcall} 17221 17222@tab 17223 17224Stdcall (used for Windows implementations only). This convention correspond 17225to the WINAPI (previously called Pascal convention) C/C++ convention under 17226Windows. A routine with this convention cleans the stack before 17227exit. This pragma cannot be applied to a dispatching call. 17228 17229@item 17230 17231@emph{DLL} 17232 17233@tab 17234 17235Synonym for Stdcall 17236 17237@item 17238 17239@emph{Win32} 17240 17241@tab 17242 17243Synonym for Stdcall 17244 17245@item 17246 17247@emph{Stubbed} 17248 17249@tab 17250 17251Stubbed is a special convention used to indicate that the body of the 17252subprogram will be entirely ignored. Any call to the subprogram 17253is converted into a raise of the @code{Program_Error} exception. If a 17254pragma @code{Import} specifies convention @code{stubbed} then no body need 17255be present at all. This convention is useful during development for the 17256inclusion of subprograms whose body has not yet been written. 17257In addition, all otherwise unrecognized convention names are also 17258treated as being synonymous with convention C. In all implementations, 17259use of such other names results in a warning. 17260 17261@end multitable 17262 17263 17264 17265@itemize * 17266 17267@item 17268"The meaning of link names. See B.1(36)." 17269@end itemize 17270 17271Link names are the actual names used by the linker. 17272 17273 17274@itemize * 17275 17276@item 17277"The manner of choosing link names when neither the link 17278name nor the address of an imported or exported entity is specified. See 17279B.1(36)." 17280@end itemize 17281 17282The default linker name is that which would be assigned by the relevant 17283external language, interpreting the Ada name as being in all lower case 17284letters. 17285 17286 17287@itemize * 17288 17289@item 17290"The effect of pragma @code{Linker_Options}. See B.1(37)." 17291@end itemize 17292 17293The string passed to @code{Linker_Options} is presented uninterpreted as 17294an argument to the link command, unless it contains ASCII.NUL characters. 17295NUL characters if they appear act as argument separators, so for example 17296 17297@example 17298pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 17299@end example 17300 17301causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 17302linker. The order of linker options is preserved for a given unit. The final 17303list of options passed to the linker is in reverse order of the elaboration 17304order. For example, linker options for a body always appear before the options 17305from the corresponding package spec. 17306 17307 17308@itemize * 17309 17310@item 17311"The contents of the visible part of package 17312@code{Interfaces} and its language-defined descendants. See B.2(1)." 17313@end itemize 17314 17315See files with prefix @code{i-} in the distributed library. 17316 17317 17318@itemize * 17319 17320@item 17321"Implementation-defined children of package 17322@code{Interfaces}. The contents of the visible part of package 17323@code{Interfaces}. See B.2(11)." 17324@end itemize 17325 17326See files with prefix @code{i-} in the distributed library. 17327 17328 17329@itemize * 17330 17331@item 17332"The types @code{Floating}, @code{Long_Floating}, 17333@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 17334@code{COBOL_Character}; and the initialization of the variables 17335@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 17336@code{Interfaces.COBOL}. See B.4(50)." 17337@end itemize 17338 17339 17340@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17341@headitem 17342 17343COBOL 17344 17345@tab 17346 17347Ada 17348 17349@item 17350 17351@emph{Floating} 17352 17353@tab 17354 17355Float 17356 17357@item 17358 17359@emph{Long_Floating} 17360 17361@tab 17362 17363(Floating) Long_Float 17364 17365@item 17366 17367@emph{Binary} 17368 17369@tab 17370 17371Integer 17372 17373@item 17374 17375@emph{Long_Binary} 17376 17377@tab 17378 17379Long_Long_Integer 17380 17381@item 17382 17383@emph{Decimal_Element} 17384 17385@tab 17386 17387Character 17388 17389@item 17390 17391@emph{COBOL_Character} 17392 17393@tab 17394 17395Character 17396 17397@end multitable 17398 17399 17400For initialization, see the file @code{i-cobol.ads} in the distributed library. 17401 17402 17403@itemize * 17404 17405@item 17406"Support for access to machine instructions. See C.1(1)." 17407@end itemize 17408 17409See documentation in file @code{s-maccod.ads} in the distributed library. 17410 17411 17412@itemize * 17413 17414@item 17415"Implementation-defined aspects of access to machine 17416operations. See C.1(9)." 17417@end itemize 17418 17419See documentation in file @code{s-maccod.ads} in the distributed library. 17420 17421 17422@itemize * 17423 17424@item 17425"Implementation-defined aspects of interrupts. See C.3(2)." 17426@end itemize 17427 17428Interrupts are mapped to signals or conditions as appropriate. See 17429definition of unit 17430@code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details 17431on the interrupts supported on a particular target. 17432 17433 17434@itemize * 17435 17436@item 17437"Implementation-defined aspects of pre-elaboration. See 17438C.4(13)." 17439@end itemize 17440 17441GNAT does not permit a partition to be restarted without reloading, 17442except under control of the debugger. 17443 17444 17445@itemize * 17446 17447@item 17448"The semantics of pragma @code{Discard_Names}. See C.5(7)." 17449@end itemize 17450 17451Pragma @code{Discard_Names} causes names of enumeration literals to 17452be suppressed. In the presence of this pragma, the Image attribute 17453provides the image of the Pos of the literal, and Value accepts 17454Pos values. 17455 17456For tagged types, when pragmas @code{Discard_Names} and @code{No_Tagged_Streams} 17457simultaneously apply, their Expanded_Name and External_Tag are initialized 17458with empty strings. This is useful to avoid exposing entity names at binary 17459level. 17460 17461 17462@itemize * 17463 17464@item 17465"The result of the @code{Task_Identification.Image} 17466attribute. See C.7.1(7)." 17467@end itemize 17468 17469The result of this attribute is a string that identifies 17470the object or component that denotes a given task. If a variable @code{Var} 17471has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, 17472where the suffix @emph{XXXXXXXX} 17473is the hexadecimal representation of the virtual address of the corresponding 17474task control block. If the variable is an array of tasks, the image of each 17475task will have the form of an indexed component indicating the position of a 17476given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a 17477component of a record, the image of the task will have the form of a selected 17478component. These rules are fully recursive, so that the image of a task that 17479is a subcomponent of a composite object corresponds to the expression that 17480designates this task. 17481 17482If a task is created by an allocator, its image depends on the context. If the 17483allocator is part of an object declaration, the rules described above are used 17484to construct its image, and this image is not affected by subsequent 17485assignments. If the allocator appears within an expression, the image 17486includes only the name of the task type. 17487 17488If the configuration pragma Discard_Names is present, or if the restriction 17489No_Implicit_Heap_Allocation is in effect, the image reduces to 17490the numeric suffix, that is to say the hexadecimal representation of the 17491virtual address of the control block of the task. 17492 17493 17494@itemize * 17495 17496@item 17497"The value of @code{Current_Task} when in a protected entry 17498or interrupt handler. See C.7.1(17)." 17499@end itemize 17500 17501Protected entries or interrupt handlers can be executed by any 17502convenient thread, so the value of @code{Current_Task} is undefined. 17503 17504 17505@itemize * 17506 17507@item 17508"The effect of calling @code{Current_Task} from an entry 17509body or interrupt handler. See C.7.1(19)." 17510@end itemize 17511 17512When GNAT can determine statically that @code{Current_Task} is called directly in 17513the body of an entry (or barrier) then a warning is emitted and @code{Program_Error} 17514is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an 17515entry body or interrupt handler is to return the identification of the task 17516currently executing the code. 17517 17518 17519@itemize * 17520 17521@item 17522"Implementation-defined aspects of 17523@code{Task_Attributes}. See C.7.2(19)." 17524@end itemize 17525 17526There are no implementation-defined aspects of @code{Task_Attributes}. 17527 17528 17529@itemize * 17530 17531@item 17532"Values of all @code{Metrics}. See D(2)." 17533@end itemize 17534 17535The metrics information for GNAT depends on the performance of the 17536underlying operating system. The sources of the run-time for tasking 17537implementation, together with the output from @emph{-gnatG} can be 17538used to determine the exact sequence of operating systems calls made 17539to implement various tasking constructs. Together with appropriate 17540information on the performance of the underlying operating system, 17541on the exact target in use, this information can be used to determine 17542the required metrics. 17543 17544 17545@itemize * 17546 17547@item 17548"The declarations of @code{Any_Priority} and 17549@code{Priority}. See D.1(11)." 17550@end itemize 17551 17552See declarations in file @code{system.ads}. 17553 17554 17555@itemize * 17556 17557@item 17558"Implementation-defined execution resources. See D.1(15)." 17559@end itemize 17560 17561There are no implementation-defined execution resources. 17562 17563 17564@itemize * 17565 17566@item 17567"Whether, on a multiprocessor, a task that is waiting for 17568access to a protected object keeps its processor busy. See D.2.1(3)." 17569@end itemize 17570 17571On a multi-processor, a task that is waiting for access to a protected 17572object does not keep its processor busy. 17573 17574 17575@itemize * 17576 17577@item 17578"The affect of implementation defined execution resources 17579on task dispatching. See D.2.1(9)." 17580@end itemize 17581 17582Tasks map to threads in the threads package used by GNAT. Where possible 17583and appropriate, these threads correspond to native threads of the 17584underlying operating system. 17585 17586 17587@itemize * 17588 17589@item 17590"Implementation-defined @emph{policy_identifiers} allowed 17591in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)." 17592@end itemize 17593 17594There are no implementation-defined policy-identifiers allowed in this 17595pragma. 17596 17597 17598@itemize * 17599 17600@item 17601"Implementation-defined aspects of priority inversion. See 17602D.2.2(16)." 17603@end itemize 17604 17605Execution of a task cannot be preempted by the implementation processing 17606of delay expirations for lower priority tasks. 17607 17608 17609@itemize * 17610 17611@item 17612"Implementation-defined task dispatching. See D.2.2(18)." 17613@end itemize 17614 17615The policy is the same as that of the underlying threads implementation. 17616 17617 17618@itemize * 17619 17620@item 17621"Implementation-defined @emph{policy_identifiers} allowed 17622in a pragma @code{Locking_Policy}. See D.3(4)." 17623@end itemize 17624 17625The two implementation defined policies permitted in GNAT are 17626@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On 17627targets that support the @code{Inheritance_Locking} policy, locking is 17628implemented by inheritance, i.e., the task owning the lock operates 17629at a priority equal to the highest priority of any task currently 17630requesting the lock. On targets that support the 17631@code{Concurrent_Readers_Locking} policy, locking is implemented with a 17632read/write lock allowing multiple protected object functions to enter 17633concurrently. 17634 17635 17636@itemize * 17637 17638@item 17639"Default ceiling priorities. See D.3(10)." 17640@end itemize 17641 17642The ceiling priority of protected objects of the type 17643@code{System.Interrupt_Priority'Last} as described in the Ada 17644Reference Manual D.3(10), 17645 17646 17647@itemize * 17648 17649@item 17650"The ceiling of any protected object used internally by 17651the implementation. See D.3(16)." 17652@end itemize 17653 17654The ceiling priority of internal protected objects is 17655@code{System.Priority'Last}. 17656 17657 17658@itemize * 17659 17660@item 17661"Implementation-defined queuing policies. See D.4(1)." 17662@end itemize 17663 17664There are no implementation-defined queuing policies. 17665 17666 17667@itemize * 17668 17669@item 17670"On a multiprocessor, any conditions that cause the 17671completion of an aborted construct to be delayed later than what is 17672specified for a single processor. See D.6(3)." 17673@end itemize 17674 17675The semantics for abort on a multi-processor is the same as on a single 17676processor, there are no further delays. 17677 17678 17679@itemize * 17680 17681@item 17682"Any operations that implicitly require heap storage 17683allocation. See D.7(8)." 17684@end itemize 17685 17686The only operation that implicitly requires heap storage allocation is 17687task creation. 17688 17689 17690@itemize * 17691 17692@item 17693"What happens when a task terminates in the presence of 17694pragma @code{No_Task_Termination}. See D.7(15)." 17695@end itemize 17696 17697Execution is erroneous in that case. 17698 17699 17700@itemize * 17701 17702@item 17703"Implementation-defined aspects of pragma 17704@code{Restrictions}. See D.7(20)." 17705@end itemize 17706 17707There are no such implementation-defined aspects. 17708 17709 17710@itemize * 17711 17712@item 17713"Implementation-defined aspects of package 17714@code{Real_Time}. See D.8(17)." 17715@end itemize 17716 17717There are no implementation defined aspects of package @code{Real_Time}. 17718 17719 17720@itemize * 17721 17722@item 17723"Implementation-defined aspects of 17724@emph{delay_statements}. See D.9(8)." 17725@end itemize 17726 17727Any difference greater than one microsecond will cause the task to be 17728delayed (see D.9(7)). 17729 17730 17731@itemize * 17732 17733@item 17734"The upper bound on the duration of interrupt blocking 17735caused by the implementation. See D.12(5)." 17736@end itemize 17737 17738The upper bound is determined by the underlying operating system. In 17739no cases is it more than 10 milliseconds. 17740 17741 17742@itemize * 17743 17744@item 17745"The means for creating and executing distributed 17746programs. See E(5)." 17747@end itemize 17748 17749The GLADE package provides a utility GNATDIST for creating and executing 17750distributed programs. See the GLADE reference manual for further details. 17751 17752 17753@itemize * 17754 17755@item 17756"Any events that can result in a partition becoming 17757inaccessible. See E.1(7)." 17758@end itemize 17759 17760See the GLADE reference manual for full details on such events. 17761 17762 17763@itemize * 17764 17765@item 17766"The scheduling policies, treatment of priorities, and 17767management of shared resources between partitions in certain cases. See 17768E.1(11)." 17769@end itemize 17770 17771See the GLADE reference manual for full details on these aspects of 17772multi-partition execution. 17773 17774 17775@itemize * 17776 17777@item 17778"Events that cause the version of a compilation unit to 17779change. See E.3(5)." 17780@end itemize 17781 17782Editing the source file of a compilation unit, or the source files of 17783any units on which it is dependent in a significant way cause the version 17784to change. No other actions cause the version number to change. All changes 17785are significant except those which affect only layout, capitalization or 17786comments. 17787 17788 17789@itemize * 17790 17791@item 17792"Whether the execution of the remote subprogram is 17793immediately aborted as a result of cancellation. See E.4(13)." 17794@end itemize 17795 17796See the GLADE reference manual for details on the effect of abort in 17797a distributed application. 17798 17799 17800@itemize * 17801 17802@item 17803"Implementation-defined aspects of the PCS. See E.5(25)." 17804@end itemize 17805 17806See the GLADE reference manual for a full description of all implementation 17807defined aspects of the PCS. 17808 17809 17810@itemize * 17811 17812@item 17813"Implementation-defined interfaces in the PCS. See 17814E.5(26)." 17815@end itemize 17816 17817See the GLADE reference manual for a full description of all 17818implementation defined interfaces. 17819 17820 17821@itemize * 17822 17823@item 17824"The values of named numbers in the package 17825@code{Decimal}. See F.2(7)." 17826@end itemize 17827 17828 17829@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17830@headitem 17831 17832Named Number 17833 17834@tab 17835 17836Value 17837 17838@item 17839 17840@emph{Max_Scale} 17841 17842@tab 17843 17844+18 17845 17846@item 17847 17848@emph{Min_Scale} 17849 17850@tab 17851 17852-18 17853 17854@item 17855 17856@emph{Min_Delta} 17857 17858@tab 17859 178601.0E-18 17861 17862@item 17863 17864@emph{Max_Delta} 17865 17866@tab 17867 178681.0E+18 17869 17870@item 17871 17872@emph{Max_Decimal_Digits} 17873 17874@tab 17875 1787618 17877 17878@end multitable 17879 17880 17881 17882@itemize * 17883 17884@item 17885"The value of @code{Max_Picture_Length} in the package 17886@code{Text_IO.Editing}. See F.3.3(16)." 17887@end itemize 17888 1788964 17890 17891 17892@itemize * 17893 17894@item 17895"The value of @code{Max_Picture_Length} in the package 17896@code{Wide_Text_IO.Editing}. See F.3.4(5)." 17897@end itemize 17898 1789964 17900 17901 17902@itemize * 17903 17904@item 17905"The accuracy actually achieved by the complex elementary 17906functions and by other complex arithmetic operations. See G.1(1)." 17907@end itemize 17908 17909Standard library functions are used for the complex arithmetic 17910operations. Only fast math mode is currently supported. 17911 17912 17913@itemize * 17914 17915@item 17916"The sign of a zero result (or a component thereof) from 17917any operator or function in @code{Numerics.Generic_Complex_Types}, when 17918@code{Real'Signed_Zeros} is True. See G.1.1(53)." 17919@end itemize 17920 17921The signs of zero values are as recommended by the relevant 17922implementation advice. 17923 17924 17925@itemize * 17926 17927@item 17928"The sign of a zero result (or a component thereof) from 17929any operator or function in 17930@code{Numerics.Generic_Complex_Elementary_Functions}, when 17931@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)." 17932@end itemize 17933 17934The signs of zero values are as recommended by the relevant 17935implementation advice. 17936 17937 17938@itemize * 17939 17940@item 17941"Whether the strict mode or the relaxed mode is the 17942default. See G.2(2)." 17943@end itemize 17944 17945The strict mode is the default. There is no separate relaxed mode. GNAT 17946provides a highly efficient implementation of strict mode. 17947 17948 17949@itemize * 17950 17951@item 17952"The result interval in certain cases of fixed-to-float 17953conversion. See G.2.1(10)." 17954@end itemize 17955 17956For cases where the result interval is implementation dependent, the 17957accuracy is that provided by performing all operations in 64-bit IEEE 17958floating-point format. 17959 17960 17961@itemize * 17962 17963@item 17964"The result of a floating point arithmetic operation in 17965overflow situations, when the @code{Machine_Overflows} attribute of the 17966result type is @code{False}. See G.2.1(13)." 17967@end itemize 17968 17969Infinite and NaN values are produced as dictated by the IEEE 17970floating-point standard. 17971Note that on machines that are not fully compliant with the IEEE 17972floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 17973must be used for achieving IEEE conforming behavior (although at the cost 17974of a significant performance penalty), so infinite and NaN values are 17975properly generated. 17976 17977 17978@itemize * 17979 17980@item 17981"The result interval for division (or exponentiation by a 17982negative exponent), when the floating point hardware implements division 17983as multiplication by a reciprocal. See G.2.1(16)." 17984@end itemize 17985 17986Not relevant, division is IEEE exact. 17987 17988 17989@itemize * 17990 17991@item 17992"The definition of close result set, which determines the 17993accuracy of certain fixed point multiplications and divisions. See 17994G.2.3(5)." 17995@end itemize 17996 17997Operations in the close result set are performed using IEEE long format 17998floating-point arithmetic. The input operands are converted to 17999floating-point, the operation is done in floating-point, and the result 18000is converted to the target type. 18001 18002 18003@itemize * 18004 18005@item 18006"Conditions on a @emph{universal_real} operand of a fixed 18007point multiplication or division for which the result shall be in the 18008perfect result set. See G.2.3(22)." 18009@end itemize 18010 18011The result is only defined to be in the perfect result set if the result 18012can be computed by a single scaling operation involving a scale factor 18013representable in 64-bits. 18014 18015 18016@itemize * 18017 18018@item 18019"The result of a fixed point arithmetic operation in 18020overflow situations, when the @code{Machine_Overflows} attribute of the 18021result type is @code{False}. See G.2.3(27)." 18022@end itemize 18023 18024Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 18025types. 18026 18027 18028@itemize * 18029 18030@item 18031"The result of an elementary function reference in 18032overflow situations, when the @code{Machine_Overflows} attribute of the 18033result type is @code{False}. See G.2.4(4)." 18034@end itemize 18035 18036IEEE infinite and Nan values are produced as appropriate. 18037 18038 18039@itemize * 18040 18041@item 18042"The value of the angle threshold, within which certain 18043elementary functions, complex arithmetic operations, and complex 18044elementary functions yield results conforming to a maximum relative 18045error bound. See G.2.4(10)." 18046@end itemize 18047 18048Information on this subject is not yet available. 18049 18050 18051@itemize * 18052 18053@item 18054"The accuracy of certain elementary functions for 18055parameters beyond the angle threshold. See G.2.4(10)." 18056@end itemize 18057 18058Information on this subject is not yet available. 18059 18060 18061@itemize * 18062 18063@item 18064"The result of a complex arithmetic operation or complex 18065elementary function reference in overflow situations, when the 18066@code{Machine_Overflows} attribute of the corresponding real type is 18067@code{False}. See G.2.6(5)." 18068@end itemize 18069 18070IEEE infinite and Nan values are produced as appropriate. 18071 18072 18073@itemize * 18074 18075@item 18076"The accuracy of certain complex arithmetic operations and 18077certain complex elementary functions for parameters (or components 18078thereof) beyond the angle threshold. See G.2.6(8)." 18079@end itemize 18080 18081Information on those subjects is not yet available. 18082 18083 18084@itemize * 18085 18086@item 18087"Information regarding bounded errors and erroneous 18088execution. See H.2(1)." 18089@end itemize 18090 18091Information on this subject is not yet available. 18092 18093 18094@itemize * 18095 18096@item 18097"Implementation-defined aspects of pragma 18098@code{Inspection_Point}. See H.3.2(8)." 18099@end itemize 18100 18101Pragma @code{Inspection_Point} ensures that the variable is live and can 18102be examined by the debugger at the inspection point. 18103 18104 18105@itemize * 18106 18107@item 18108"Implementation-defined aspects of pragma 18109@code{Restrictions}. See H.4(25)." 18110@end itemize 18111 18112There are no implementation-defined aspects of pragma @code{Restrictions}. The 18113use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 18114generated code. Checks must suppressed by use of pragma @code{Suppress}. 18115 18116 18117@itemize * 18118 18119@item 18120"Any restrictions on pragma @code{Restrictions}. See 18121H.4(27)." 18122@end itemize 18123 18124There are no restrictions on pragma @code{Restrictions}. 18125 18126@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 18127@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25a}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25b} 18128@chapter Intrinsic Subprograms 18129 18130 18131@geindex Intrinsic Subprograms 18132 18133GNAT allows a user application program to write the declaration: 18134 18135@example 18136pragma Import (Intrinsic, name); 18137@end example 18138 18139providing that the name corresponds to one of the implemented intrinsic 18140subprograms in GNAT, and that the parameter profile of the referenced 18141subprogram meets the requirements. This chapter describes the set of 18142implemented intrinsic subprograms, and the requirements on parameter profiles. 18143Note that no body is supplied; as with other uses of pragma Import, the 18144body is supplied elsewhere (in this case by the compiler itself). Note 18145that any use of this feature is potentially non-portable, since the 18146Ada standard does not require Ada compilers to implement this feature. 18147 18148@menu 18149* Intrinsic Operators:: 18150* Compilation_ISO_Date:: 18151* Compilation_Date:: 18152* Compilation_Time:: 18153* Enclosing_Entity:: 18154* Exception_Information:: 18155* Exception_Message:: 18156* Exception_Name:: 18157* File:: 18158* Line:: 18159* Shifts and Rotates:: 18160* Source_Location:: 18161 18162@end menu 18163 18164@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms 18165@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25c}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{25d} 18166@section Intrinsic Operators 18167 18168 18169@geindex Intrinsic operator 18170 18171All the predefined numeric operators in package Standard 18172in @code{pragma Import (Intrinsic,..)} 18173declarations. In the binary operator case, the operands must have the same 18174size. The operand or operands must also be appropriate for 18175the operator. For example, for addition, the operands must 18176both be floating-point or both be fixed-point, and the 18177right operand for @code{"**"} must have a root type of 18178@code{Standard.Integer'Base}. 18179You can use an intrinsic operator declaration as in the following example: 18180 18181@example 18182type Int1 is new Integer; 18183type Int2 is new Integer; 18184 18185function "+" (X1 : Int1; X2 : Int2) return Int1; 18186function "+" (X1 : Int1; X2 : Int2) return Int2; 18187pragma Import (Intrinsic, "+"); 18188@end example 18189 18190This declaration would permit 'mixed mode' arithmetic on items 18191of the differing types @code{Int1} and @code{Int2}. 18192It is also possible to specify such operators for private types, if the 18193full views are appropriate arithmetic types. 18194 18195@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms 18196@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{25f} 18197@section Compilation_ISO_Date 18198 18199 18200@geindex Compilation_ISO_Date 18201 18202This intrinsic subprogram is used in the implementation of the 18203library package @code{GNAT.Source_Info}. The only useful use of the 18204intrinsic import in this case is the one in this unit, so an 18205application program should simply call the function 18206@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of 18207the current compilation (in local time format YYYY-MM-DD). 18208 18209@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms 18210@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{260}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{261} 18211@section Compilation_Date 18212 18213 18214@geindex Compilation_Date 18215 18216Same as Compilation_ISO_Date, except the string is in the form 18217MMM DD YYYY. 18218 18219@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 18220@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{262}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{263} 18221@section Compilation_Time 18222 18223 18224@geindex Compilation_Time 18225 18226This intrinsic subprogram is used in the implementation of the 18227library package @code{GNAT.Source_Info}. The only useful use of the 18228intrinsic import in this case is the one in this unit, so an 18229application program should simply call the function 18230@code{GNAT.Source_Info.Compilation_Time} to obtain the time of 18231the current compilation (in local time format HH:MM:SS). 18232 18233@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 18234@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{264}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{265} 18235@section Enclosing_Entity 18236 18237 18238@geindex Enclosing_Entity 18239 18240This intrinsic subprogram is used in the implementation of the 18241library package @code{GNAT.Source_Info}. The only useful use of the 18242intrinsic import in this case is the one in this unit, so an 18243application program should simply call the function 18244@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 18245the current subprogram, package, task, entry, or protected subprogram. 18246 18247@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 18248@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{266}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{267} 18249@section Exception_Information 18250 18251 18252@geindex Exception_Information' 18253 18254This intrinsic subprogram is used in the implementation of the 18255library package @code{GNAT.Current_Exception}. The only useful 18256use of the intrinsic import in this case is the one in this unit, 18257so an application program should simply call the function 18258@code{GNAT.Current_Exception.Exception_Information} to obtain 18259the exception information associated with the current exception. 18260 18261@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 18262@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{268}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{269} 18263@section Exception_Message 18264 18265 18266@geindex Exception_Message 18267 18268This intrinsic subprogram is used in the implementation of the 18269library package @code{GNAT.Current_Exception}. The only useful 18270use of the intrinsic import in this case is the one in this unit, 18271so an application program should simply call the function 18272@code{GNAT.Current_Exception.Exception_Message} to obtain 18273the message associated with the current exception. 18274 18275@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 18276@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26b} 18277@section Exception_Name 18278 18279 18280@geindex Exception_Name 18281 18282This intrinsic subprogram is used in the implementation of the 18283library package @code{GNAT.Current_Exception}. The only useful 18284use of the intrinsic import in this case is the one in this unit, 18285so an application program should simply call the function 18286@code{GNAT.Current_Exception.Exception_Name} to obtain 18287the name of the current exception. 18288 18289@node File,Line,Exception_Name,Intrinsic Subprograms 18290@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{26c}@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26d} 18291@section File 18292 18293 18294@geindex File 18295 18296This intrinsic subprogram is used in the implementation of the 18297library package @code{GNAT.Source_Info}. The only useful use of the 18298intrinsic import in this case is the one in this unit, so an 18299application program should simply call the function 18300@code{GNAT.Source_Info.File} to obtain the name of the current 18301file. 18302 18303@node Line,Shifts and Rotates,File,Intrinsic Subprograms 18304@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{26e}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{26f} 18305@section Line 18306 18307 18308@geindex Line 18309 18310This intrinsic subprogram is used in the implementation of the 18311library package @code{GNAT.Source_Info}. The only useful use of the 18312intrinsic import in this case is the one in this unit, so an 18313application program should simply call the function 18314@code{GNAT.Source_Info.Line} to obtain the number of the current 18315source line. 18316 18317@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 18318@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{270}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{271} 18319@section Shifts and Rotates 18320 18321 18322@geindex Shift_Left 18323 18324@geindex Shift_Right 18325 18326@geindex Shift_Right_Arithmetic 18327 18328@geindex Rotate_Left 18329 18330@geindex Rotate_Right 18331 18332In standard Ada, the shift and rotate functions are available only 18333for the predefined modular types in package @code{Interfaces}. However, in 18334GNAT it is possible to define these functions for any integer 18335type (signed or modular), as in this example: 18336 18337@example 18338function Shift_Left 18339 (Value : T; 18340 Amount : Natural) return T; 18341@end example 18342 18343The function name must be one of 18344Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 18345Rotate_Right. T must be an integer type. T'Size must be 183468, 16, 32 or 64 bits; if T is modular, the modulus 18347must be 2**8, 2**16, 2**32 or 2**64. 18348The result type must be the same as the type of @code{Value}. 18349The shift amount must be Natural. 18350The formal parameter names can be anything. 18351 18352A more convenient way of providing these shift operators is to use 18353the Provide_Shift_Operators pragma, which provides the function declarations 18354and corresponding pragma Import's for all five shift functions. 18355 18356@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 18357@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{272}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{273} 18358@section Source_Location 18359 18360 18361@geindex Source_Location 18362 18363This intrinsic subprogram is used in the implementation of the 18364library routine @code{GNAT.Source_Info}. The only useful use of the 18365intrinsic import in this case is the one in this unit, so an 18366application program should simply call the function 18367@code{GNAT.Source_Info.Source_Location} to obtain the current 18368source file location. 18369 18370@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 18371@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{274}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{275} 18372@chapter Representation Clauses and Pragmas 18373 18374 18375@geindex Representation Clauses 18376 18377@geindex Representation Clause 18378 18379@geindex Representation Pragma 18380 18381@geindex Pragma 18382@geindex representation 18383 18384This section describes the representation clauses accepted by GNAT, and 18385their effect on the representation of corresponding data objects. 18386 18387GNAT fully implements Annex C (Systems Programming). This means that all 18388the implementation advice sections in chapter 13 are fully implemented. 18389However, these sections only require a minimal level of support for 18390representation clauses. GNAT provides much more extensive capabilities, 18391and this section describes the additional capabilities provided. 18392 18393@menu 18394* Alignment Clauses:: 18395* Size Clauses:: 18396* Storage_Size Clauses:: 18397* Size of Variant Record Objects:: 18398* Biased Representation:: 18399* Value_Size and Object_Size Clauses:: 18400* Component_Size Clauses:: 18401* Bit_Order Clauses:: 18402* Effect of Bit_Order on Byte Ordering:: 18403* Pragma Pack for Arrays:: 18404* Pragma Pack for Records:: 18405* Record Representation Clauses:: 18406* Handling of Records with Holes:: 18407* Enumeration Clauses:: 18408* Address Clauses:: 18409* Use of Address Clauses for Memory-Mapped I/O:: 18410* Effect of Convention on Representation:: 18411* Conventions and Anonymous Access Types:: 18412* Determining the Representations chosen by GNAT:: 18413 18414@end menu 18415 18416@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 18417@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{276}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{277} 18418@section Alignment Clauses 18419 18420 18421@geindex Alignment Clause 18422 18423GNAT requires that all alignment clauses specify 0 or a power of 2, and 18424all default alignments are always a power of 2. Specifying 0 is the 18425same as specifying 1. 18426 18427The default alignment values are as follows: 18428 18429 18430@itemize * 18431 18432@item 18433@emph{Elementary Types}. 18434 18435For elementary types, the alignment is the minimum of the actual size of 18436objects of the type divided by @code{Storage_Unit}, 18437and the maximum alignment supported by the target. 18438(This maximum alignment is given by the GNAT-specific attribute 18439@code{Standard'Maximum_Alignment}; see @ref{191,,Attribute Maximum_Alignment}.) 18440 18441@geindex Maximum_Alignment attribute 18442 18443For example, for type @code{Long_Float}, the object size is 8 bytes, and the 18444default alignment will be 8 on any target that supports alignments 18445this large, but on some targets, the maximum alignment may be smaller 18446than 8, in which case objects of type @code{Long_Float} will be maximally 18447aligned. 18448 18449@item 18450@emph{Arrays}. 18451 18452For arrays, the alignment is equal to the alignment of the component type 18453for the normal case where no packing or component size is given. If the 18454array is packed, and the packing is effective (see separate section on 18455packed arrays), then the alignment will be either 4, 2, or 1 for long packed 18456arrays or arrays whose length is not known at compile time, depending on 18457whether the component size is divisible by 4, 2, or is odd. For short packed 18458arrays, which are handled internally as modular types, the alignment 18459will be as described for elementary types, e.g. a packed array of length 1846031 bits will have an object size of four bytes, and an alignment of 4. 18461 18462@item 18463@emph{Records}. 18464 18465For the normal unpacked case, the alignment of a record is equal to 18466the maximum alignment of any of its components. For tagged records, this 18467includes the implicit access type used for the tag. If a pragma @code{Pack} 18468is used and all components are packable (see separate section on pragma 18469@code{Pack}), then the resulting alignment is 1, unless the layout of the 18470record makes it profitable to increase it. 18471 18472A special case is when: 18473 18474 18475@itemize * 18476 18477@item 18478the size of the record is given explicitly, or a 18479full record representation clause is given, and 18480 18481@item 18482the size of the record is 2, 4, or 8 bytes. 18483@end itemize 18484 18485In this case, an alignment is chosen to match the 18486size of the record. For example, if we have: 18487 18488@example 18489type Small is record 18490 A, B : Character; 18491end record; 18492for Small'Size use 16; 18493@end example 18494 18495then the default alignment of the record type @code{Small} is 2, not 1. This 18496leads to more efficient code when the record is treated as a unit, and also 18497allows the type to specified as @code{Atomic} on architectures requiring 18498strict alignment. 18499@end itemize 18500 18501An alignment clause may specify a larger alignment than the default value 18502up to some maximum value dependent on the target (obtainable by using the 18503attribute reference @code{Standard'Maximum_Alignment}). It may also specify 18504a smaller alignment than the default value for enumeration, integer and 18505fixed point types, as well as for record types, for example 18506 18507@example 18508type V is record 18509 A : Integer; 18510end record; 18511 18512for V'alignment use 1; 18513@end example 18514 18515@geindex Alignment 18516@geindex default 18517 18518The default alignment for the type @code{V} is 4, as a result of the 18519Integer field in the record, but it is permissible, as shown, to 18520override the default alignment of the record with a smaller value. 18521 18522@geindex Alignment 18523@geindex subtypes 18524 18525Note that according to the Ada standard, an alignment clause applies only 18526to the first named subtype. If additional subtypes are declared, then the 18527compiler is allowed to choose any alignment it likes, and there is no way 18528to control this choice. Consider: 18529 18530@example 18531type R is range 1 .. 10_000; 18532for R'Alignment use 1; 18533subtype RS is R range 1 .. 1000; 18534@end example 18535 18536The alignment clause specifies an alignment of 1 for the first named subtype 18537@code{R} but this does not necessarily apply to @code{RS}. When writing 18538portable Ada code, you should avoid writing code that explicitly or 18539implicitly relies on the alignment of such subtypes. 18540 18541For the GNAT compiler, if an explicit alignment clause is given, this 18542value is also used for any subsequent subtypes. So for GNAT, in the 18543above example, you can count on the alignment of @code{RS} being 1. But this 18544assumption is non-portable, and other compilers may choose different 18545alignments for the subtype @code{RS}. 18546 18547@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 18548@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{279} 18549@section Size Clauses 18550 18551 18552@geindex Size Clause 18553 18554The default size for a type @code{T} is obtainable through the 18555language-defined attribute @code{T'Size} and also through the 18556equivalent GNAT-defined attribute @code{T'Value_Size}. 18557For objects of type @code{T}, GNAT will generally increase the type size 18558so that the object size (obtainable through the GNAT-defined attribute 18559@code{T'Object_Size}) 18560is a multiple of @code{T'Alignment * Storage_Unit}. 18561 18562For example: 18563 18564@example 18565type Smallint is range 1 .. 6; 18566 18567type Rec is record 18568 Y1 : integer; 18569 Y2 : boolean; 18570end record; 18571@end example 18572 18573In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 18574as specified by the RM rules, 18575but objects of this type will have a size of 8 18576(@code{Smallint'Object_Size} = 8), 18577since objects by default occupy an integral number 18578of storage units. On some targets, notably older 18579versions of the Digital Alpha, the size of stand 18580alone objects of this type may be 32, reflecting 18581the inability of the hardware to do byte load/stores. 18582 18583Similarly, the size of type @code{Rec} is 40 bits 18584(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 18585the alignment is 4, so objects of this type will have 18586their size increased to 64 bits so that it is a multiple 18587of the alignment (in bits). This decision is 18588in accordance with the specific Implementation Advice in RM 13.3(43): 18589 18590@quotation 18591 18592"A @code{Size} clause should be supported for an object if the specified 18593@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 18594to a size in storage elements that is a multiple of the object's 18595@code{Alignment} (if the @code{Alignment} is nonzero)." 18596@end quotation 18597 18598An explicit size clause may be used to override the default size by 18599increasing it. For example, if we have: 18600 18601@example 18602type My_Boolean is new Boolean; 18603for My_Boolean'Size use 32; 18604@end example 18605 18606then values of this type will always be 32 bits long. In the case of 18607discrete types, the size can be increased up to 64 bits, with the effect 18608that the entire specified field is used to hold the value, sign- or 18609zero-extended as appropriate. If more than 64 bits is specified, then 18610padding space is allocated after the value, and a warning is issued that 18611there are unused bits. 18612 18613Similarly the size of records and arrays may be increased, and the effect 18614is to add padding bits after the value. This also causes a warning message 18615to be generated. 18616 18617The largest Size value permitted in GNAT is 2**31-1. Since this is a 18618Size in bits, this corresponds to an object of size 256 megabytes (minus 18619one). This limitation is true on all targets. The reason for this 18620limitation is that it improves the quality of the code in many cases 18621if it is known that a Size value can be accommodated in an object of 18622type Integer. 18623 18624@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 18625@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27a}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27b} 18626@section Storage_Size Clauses 18627 18628 18629@geindex Storage_Size Clause 18630 18631For tasks, the @code{Storage_Size} clause specifies the amount of space 18632to be allocated for the task stack. This cannot be extended, and if the 18633stack is exhausted, then @code{Storage_Error} will be raised (if stack 18634checking is enabled). Use a @code{Storage_Size} attribute definition clause, 18635or a @code{Storage_Size} pragma in the task definition to set the 18636appropriate required size. A useful technique is to include in every 18637task definition a pragma of the form: 18638 18639@example 18640pragma Storage_Size (Default_Stack_Size); 18641@end example 18642 18643Then @code{Default_Stack_Size} can be defined in a global package, and 18644modified as required. Any tasks requiring stack sizes different from the 18645default can have an appropriate alternative reference in the pragma. 18646 18647You can also use the @emph{-d} binder switch to modify the default stack 18648size. 18649 18650For access types, the @code{Storage_Size} clause specifies the maximum 18651space available for allocation of objects of the type. If this space is 18652exceeded then @code{Storage_Error} will be raised by an allocation attempt. 18653In the case where the access type is declared local to a subprogram, the 18654use of a @code{Storage_Size} clause triggers automatic use of a special 18655predefined storage pool (@code{System.Pool_Size}) that ensures that all 18656space for the pool is automatically reclaimed on exit from the scope in 18657which the type is declared. 18658 18659A special case recognized by the compiler is the specification of a 18660@code{Storage_Size} of zero for an access type. This means that no 18661items can be allocated from the pool, and this is recognized at compile 18662time, and all the overhead normally associated with maintaining a fixed 18663size storage pool is eliminated. Consider the following example: 18664 18665@example 18666procedure p is 18667 type R is array (Natural) of Character; 18668 type P is access all R; 18669 for P'Storage_Size use 0; 18670 -- Above access type intended only for interfacing purposes 18671 18672 y : P; 18673 18674 procedure g (m : P); 18675 pragma Import (C, g); 18676 18677 -- ... 18678 18679begin 18680 -- ... 18681 y := new R; 18682end; 18683@end example 18684 18685As indicated in this example, these dummy storage pools are often useful in 18686connection with interfacing where no object will ever be allocated. If you 18687compile the above example, you get the warning: 18688 18689@example 18690p.adb:16:09: warning: allocation from empty storage pool 18691p.adb:16:09: warning: Storage_Error will be raised at run time 18692@end example 18693 18694Of course in practice, there will not be any explicit allocators in the 18695case of such an access declaration. 18696 18697@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 18698@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27c}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{27d} 18699@section Size of Variant Record Objects 18700 18701 18702@geindex Size 18703@geindex variant record objects 18704 18705@geindex Variant record objects 18706@geindex size 18707 18708In the case of variant record objects, there is a question whether Size gives 18709information about a particular variant, or the maximum size required 18710for any variant. Consider the following program 18711 18712@example 18713with Text_IO; use Text_IO; 18714procedure q is 18715 type R1 (A : Boolean := False) is record 18716 case A is 18717 when True => X : Character; 18718 when False => null; 18719 end case; 18720 end record; 18721 18722 V1 : R1 (False); 18723 V2 : R1; 18724 18725begin 18726 Put_Line (Integer'Image (V1'Size)); 18727 Put_Line (Integer'Image (V2'Size)); 18728end q; 18729@end example 18730 18731Here we are dealing with a variant record, where the True variant 18732requires 16 bits, and the False variant requires 8 bits. 18733In the above example, both V1 and V2 contain the False variant, 18734which is only 8 bits long. However, the result of running the 18735program is: 18736 18737@example 187388 1873916 18740@end example 18741 18742The reason for the difference here is that the discriminant value of 18743V1 is fixed, and will always be False. It is not possible to assign 18744a True variant value to V1, therefore 8 bits is sufficient. On the 18745other hand, in the case of V2, the initial discriminant value is 18746False (from the default), but it is possible to assign a True 18747variant value to V2, therefore 16 bits must be allocated for V2 18748in the general case, even fewer bits may be needed at any particular 18749point during the program execution. 18750 18751As can be seen from the output of this program, the @code{'Size} 18752attribute applied to such an object in GNAT gives the actual allocated 18753size of the variable, which is the largest size of any of the variants. 18754The Ada Reference Manual is not completely clear on what choice should 18755be made here, but the GNAT behavior seems most consistent with the 18756language in the RM. 18757 18758In some cases, it may be desirable to obtain the size of the current 18759variant, rather than the size of the largest variant. This can be 18760achieved in GNAT by making use of the fact that in the case of a 18761subprogram parameter, GNAT does indeed return the size of the current 18762variant (because a subprogram has no way of knowing how much space 18763is actually allocated for the actual). 18764 18765Consider the following modified version of the above program: 18766 18767@example 18768with Text_IO; use Text_IO; 18769procedure q is 18770 type R1 (A : Boolean := False) is record 18771 case A is 18772 when True => X : Character; 18773 when False => null; 18774 end case; 18775 end record; 18776 18777 V2 : R1; 18778 18779 function Size (V : R1) return Integer is 18780 begin 18781 return V'Size; 18782 end Size; 18783 18784begin 18785 Put_Line (Integer'Image (V2'Size)); 18786 Put_Line (Integer'Image (Size (V2))); 18787 V2 := (True, 'x'); 18788 Put_Line (Integer'Image (V2'Size)); 18789 Put_Line (Integer'Image (Size (V2))); 18790end q; 18791@end example 18792 18793The output from this program is 18794 18795@example 1879616 187978 1879816 1879916 18800@end example 18801 18802Here we see that while the @code{'Size} attribute always returns 18803the maximum size, regardless of the current variant value, the 18804@code{Size} function does indeed return the size of the current 18805variant value. 18806 18807@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18808@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{27e}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{27f} 18809@section Biased Representation 18810 18811 18812@geindex Size for biased representation 18813 18814@geindex Biased representation 18815 18816In the case of scalars with a range starting at other than zero, it is 18817possible in some cases to specify a size smaller than the default minimum 18818value, and in such cases, GNAT uses an unsigned biased representation, 18819in which zero is used to represent the lower bound, and successive values 18820represent successive values of the type. 18821 18822For example, suppose we have the declaration: 18823 18824@example 18825type Small is range -7 .. -4; 18826for Small'Size use 2; 18827@end example 18828 18829Although the default size of type @code{Small} is 4, the @code{Size} 18830clause is accepted by GNAT and results in the following representation 18831scheme: 18832 18833@example 18834-7 is represented as 2#00# 18835-6 is represented as 2#01# 18836-5 is represented as 2#10# 18837-4 is represented as 2#11# 18838@end example 18839 18840Biased representation is only used if the specified @code{Size} clause 18841cannot be accepted in any other manner. These reduced sizes that force 18842biased representation can be used for all discrete types except for 18843enumeration types for which a representation clause is given. 18844 18845@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18846@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{280}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{281} 18847@section Value_Size and Object_Size Clauses 18848 18849 18850@geindex Value_Size 18851 18852@geindex Object_Size 18853 18854@geindex Size 18855@geindex of objects 18856 18857In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 18858number of bits required to hold values of type @code{T}. 18859Although this interpretation was allowed in Ada 83, it was not required, 18860and this requirement in practice can cause some significant difficulties. 18861For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 18862However, in Ada 95 and Ada 2005, 18863@code{Natural'Size} is 18864typically 31. This means that code may change in behavior when moving 18865from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18866 18867@example 18868type Rec is record; 18869 A : Natural; 18870 B : Natural; 18871end record; 18872 18873for Rec use record 18874 at 0 range 0 .. Natural'Size - 1; 18875 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18876end record; 18877@end example 18878 18879In the above code, since the typical size of @code{Natural} objects 18880is 32 bits and @code{Natural'Size} is 31, the above code can cause 18881unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18882there are cases where the fact that the object size can exceed the 18883size of the type causes surprises. 18884 18885To help get around this problem GNAT provides two implementation 18886defined attributes, @code{Value_Size} and @code{Object_Size}. When 18887applied to a type, these attributes yield the size of the type 18888(corresponding to the RM defined size attribute), and the size of 18889objects of the type respectively. 18890 18891The @code{Object_Size} is used for determining the default size of 18892objects and components. This size value can be referred to using the 18893@code{Object_Size} attribute. The phrase 'is used' here means that it is 18894the basis of the determination of the size. The backend is free to 18895pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18896character might be stored in 32 bits on a machine with no efficient 18897byte access instructions such as the Alpha. 18898 18899The default rules for the value of @code{Object_Size} for 18900discrete types are as follows: 18901 18902 18903@itemize * 18904 18905@item 18906The @code{Object_Size} for base subtypes reflect the natural hardware 18907size in bits (run the compiler with @emph{-gnatS} to find those values 18908for numeric types). Enumeration types and fixed-point base subtypes have 189098, 16, 32, or 64 bits for this size, depending on the range of values 18910to be stored. 18911 18912@item 18913The @code{Object_Size} of a subtype is the same as the 18914@code{Object_Size} of 18915the type from which it is obtained. 18916 18917@item 18918The @code{Object_Size} of a derived base type is copied from the parent 18919base type, and the @code{Object_Size} of a derived first subtype is copied 18920from the parent first subtype. 18921@end itemize 18922 18923The @code{Value_Size} attribute 18924is the (minimum) number of bits required to store a value 18925of the type. 18926This value is used to determine how tightly to pack 18927records or arrays with components of this type, and also affects 18928the semantics of unchecked conversion (unchecked conversions where 18929the @code{Value_Size} values differ generate a warning, and are potentially 18930target dependent). 18931 18932The default rules for the value of @code{Value_Size} are as follows: 18933 18934 18935@itemize * 18936 18937@item 18938The @code{Value_Size} for a base subtype is the minimum number of bits 18939required to store all values of the type (including the sign bit 18940only if negative values are possible). 18941 18942@item 18943If a subtype statically matches the first subtype of a given type, then it has 18944by default the same @code{Value_Size} as the first subtype. This is a 18945consequence of RM 13.1(14): "if two subtypes statically match, 18946then their subtype-specific aspects are the same".) 18947 18948@item 18949All other subtypes have a @code{Value_Size} corresponding to the minimum 18950number of bits required to store all values of the subtype. For 18951dynamic bounds, it is assumed that the value can range down or up 18952to the corresponding bound of the ancestor 18953@end itemize 18954 18955The RM defined attribute @code{Size} corresponds to the 18956@code{Value_Size} attribute. 18957 18958The @code{Size} attribute may be defined for a first-named subtype. This sets 18959the @code{Value_Size} of 18960the first-named subtype to the given value, and the 18961@code{Object_Size} of this first-named subtype to the given value padded up 18962to an appropriate boundary. It is a consequence of the default rules 18963above that this @code{Object_Size} will apply to all further subtypes. On the 18964other hand, @code{Value_Size} is affected only for the first subtype, any 18965dynamic subtypes obtained from it directly, and any statically matching 18966subtypes. The @code{Value_Size} of any other static subtypes is not affected. 18967 18968@code{Value_Size} and 18969@code{Object_Size} may be explicitly set for any subtype using 18970an attribute definition clause. Note that the use of these attributes 18971can cause the RM 13.1(14) rule to be violated. If two access types 18972reference aliased objects whose subtypes have differing @code{Object_Size} 18973values as a result of explicit attribute definition clauses, then it 18974is illegal to convert from one access subtype to the other. For a more 18975complete description of this additional legality rule, see the 18976description of the @code{Object_Size} attribute. 18977 18978To get a feel for the difference, consider the following examples (note 18979that in each case the base is @code{Short_Short_Integer} with a size of 8): 18980 18981 18982@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 18983@headitem 18984 18985Type or subtype declaration 18986 18987@tab 18988 18989Object_Size 18990 18991@tab 18992 18993Value_Size 18994 18995@item 18996 18997@code{type x1 is range 0 .. 5;} 18998 18999@tab 19000 190018 19002 19003@tab 19004 190053 19006 19007@item 19008 19009@code{type x2 is range 0 .. 5;} 19010@code{for x2'size use 12;} 19011 19012@tab 19013 1901416 19015 19016@tab 19017 1901812 19019 19020@item 19021 19022@code{subtype x3 is x2 range 0 .. 3;} 19023 19024@tab 19025 1902616 19027 19028@tab 19029 190302 19031 19032@item 19033 19034@code{subtype x4 is x2'base range 0 .. 10;} 19035 19036@tab 19037 190388 19039 19040@tab 19041 190424 19043 19044@item 19045 19046@code{dynamic : x2'Base range -64 .. +63;} 19047 19048@tab 19049 19050@tab 19051 19052@item 19053 19054@code{subtype x5 is x2 range 0 .. dynamic;} 19055 19056@tab 19057 1905816 19059 19060@tab 19061 190623* 19063 19064@item 19065 19066@code{subtype x6 is x2'base range 0 .. dynamic;} 19067 19068@tab 19069 190708 19071 19072@tab 19073 190747* 19075 19076@end multitable 19077 19078 19079Note: the entries marked '*' are not actually specified by the Ada 19080Reference Manual, which has nothing to say about size in the dynamic 19081case. What GNAT does is to allocate sufficient bits to accomodate any 19082possible dynamic values for the bounds at run-time. 19083 19084So far, so good, but GNAT has to obey the RM rules, so the question is 19085under what conditions must the RM @code{Size} be used. 19086The following is a list 19087of the occasions on which the RM @code{Size} must be used: 19088 19089 19090@itemize * 19091 19092@item 19093Component size for packed arrays or records 19094 19095@item 19096Value of the attribute @code{Size} for a type 19097 19098@item 19099Warning about sizes not matching for unchecked conversion 19100@end itemize 19101 19102For record types, the @code{Object_Size} is always a multiple of the 19103alignment of the type (this is true for all types). In some cases the 19104@code{Value_Size} can be smaller. Consider: 19105 19106@example 19107type R is record 19108 X : Integer; 19109 Y : Character; 19110end record; 19111@end example 19112 19113On a typical 32-bit architecture, the X component will occupy four bytes 19114and the Y component will occupy one byte, for a total of 5 bytes. As a 19115result @code{R'Value_Size} will be 40 (bits) since this is the minimum size 19116required to store a value of this type. For example, it is permissible 19117to have a component of type R in an array whose component size is 19118specified to be 40 bits. 19119 19120However, @code{R'Object_Size} will be 64 (bits). The difference is due to 19121the alignment requirement for objects of the record type. The X 19122component will require four-byte alignment because that is what type 19123Integer requires, whereas the Y component, a Character, will only 19124require 1-byte alignment. Since the alignment required for X is the 19125greatest of all the components' alignments, that is the alignment 19126required for the enclosing record type, i.e., 4 bytes or 32 bits. As 19127indicated above, the actual object size must be rounded up so that it is 19128a multiple of the alignment value. Therefore, 40 bits rounded up to the 19129next multiple of 32 yields 64 bits. 19130 19131For all other types, the @code{Object_Size} 19132and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). 19133Only @code{Size} may be specified for such types. 19134 19135Note that @code{Value_Size} can be used to force biased representation 19136for a particular subtype. Consider this example: 19137 19138@example 19139type R is (A, B, C, D, E, F); 19140subtype RAB is R range A .. B; 19141subtype REF is R range E .. F; 19142@end example 19143 19144By default, @code{RAB} 19145has a size of 1 (sufficient to accommodate the representation 19146of @code{A} and @code{B}, 0 and 1), and @code{REF} 19147has a size of 3 (sufficient to accommodate the representation 19148of @code{E} and @code{F}, 4 and 5). But if we add the 19149following @code{Value_Size} attribute definition clause: 19150 19151@example 19152for REF'Value_Size use 1; 19153@end example 19154 19155then biased representation is forced for @code{REF}, 19156and 0 will represent @code{E} and 1 will represent @code{F}. 19157A warning is issued when a @code{Value_Size} attribute 19158definition clause forces biased representation. This 19159warning can be turned off using @code{-gnatw.B}. 19160 19161@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 19162@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{282}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{283} 19163@section Component_Size Clauses 19164 19165 19166@geindex Component_Size Clause 19167 19168Normally, the value specified in a component size clause must be consistent 19169with the subtype of the array component with regard to size and alignment. 19170In other words, the value specified must be at least equal to the size 19171of this subtype, and must be a multiple of the alignment value. 19172 19173In addition, component size clauses are allowed which cause the array 19174to be packed, by specifying a smaller value. A first case is for 19175component size values in the range 1 through 63. The value specified 19176must not be smaller than the Size of the subtype. GNAT will accurately 19177honor all packing requests in this range. For example, if we have: 19178 19179@example 19180type r is array (1 .. 8) of Natural; 19181for r'Component_Size use 31; 19182@end example 19183 19184then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 19185Of course access to the components of such an array is considerably 19186less efficient than if the natural component size of 32 is used. 19187A second case is when the subtype of the component is a record type 19188padded because of its default alignment. For example, if we have: 19189 19190@example 19191type r is record 19192 i : Integer; 19193 j : Integer; 19194 b : Boolean; 19195end record; 19196 19197type a is array (1 .. 8) of r; 19198for a'Component_Size use 72; 19199@end example 19200 19201then the resulting array has a length of 72 bytes, instead of 96 bytes 19202if the alignment of the record (4) was obeyed. 19203 19204Note that there is no point in giving both a component size clause 19205and a pragma Pack for the same array type. if such duplicate 19206clauses are given, the pragma Pack will be ignored. 19207 19208@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 19209@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{285} 19210@section Bit_Order Clauses 19211 19212 19213@geindex Bit_Order Clause 19214 19215@geindex bit ordering 19216 19217@geindex ordering 19218@geindex of bits 19219 19220For record subtypes, GNAT permits the specification of the @code{Bit_Order} 19221attribute. The specification may either correspond to the default bit 19222order for the target, in which case the specification has no effect and 19223places no additional restrictions, or it may be for the non-standard 19224setting (that is the opposite of the default). 19225 19226In the case where the non-standard value is specified, the effect is 19227to renumber bits within each byte, but the ordering of bytes is not 19228affected. There are certain 19229restrictions placed on component clauses as follows: 19230 19231 19232@itemize * 19233 19234@item 19235Components fitting within a single storage unit. 19236 19237These are unrestricted, and the effect is merely to renumber bits. For 19238example if we are on a little-endian machine with @code{Low_Order_First} 19239being the default, then the following two declarations have exactly 19240the same effect: 19241 19242@example 19243type R1 is record 19244 A : Boolean; 19245 B : Integer range 1 .. 120; 19246end record; 19247 19248for R1 use record 19249 A at 0 range 0 .. 0; 19250 B at 0 range 1 .. 7; 19251end record; 19252 19253type R2 is record 19254 A : Boolean; 19255 B : Integer range 1 .. 120; 19256end record; 19257 19258for R2'Bit_Order use High_Order_First; 19259 19260for R2 use record 19261 A at 0 range 7 .. 7; 19262 B at 0 range 0 .. 6; 19263end record; 19264@end example 19265 19266The useful application here is to write the second declaration with the 19267@code{Bit_Order} attribute definition clause, and know that it will be treated 19268the same, regardless of whether the target is little-endian or big-endian. 19269 19270@item 19271Components occupying an integral number of bytes. 19272 19273These are components that exactly fit in two or more bytes. Such component 19274declarations are allowed, but have no effect, since it is important to realize 19275that the @code{Bit_Order} specification does not affect the ordering of bytes. 19276In particular, the following attempt at getting an endian-independent integer 19277does not work: 19278 19279@example 19280type R2 is record 19281 A : Integer; 19282end record; 19283 19284for R2'Bit_Order use High_Order_First; 19285 19286for R2 use record 19287 A at 0 range 0 .. 31; 19288end record; 19289@end example 19290 19291This declaration will result in a little-endian integer on a 19292little-endian machine, and a big-endian integer on a big-endian machine. 19293If byte flipping is required for interoperability between big- and 19294little-endian machines, this must be explicitly programmed. This capability 19295is not provided by @code{Bit_Order}. 19296 19297@item 19298Components that are positioned across byte boundaries. 19299 19300but do not occupy an integral number of bytes. Given that bytes are not 19301reordered, such fields would occupy a non-contiguous sequence of bits 19302in memory, requiring non-trivial code to reassemble. They are for this 19303reason not permitted, and any component clause specifying such a layout 19304will be flagged as illegal by GNAT. 19305@end itemize 19306 19307Since the misconception that Bit_Order automatically deals with all 19308endian-related incompatibilities is a common one, the specification of 19309a component field that is an integral number of bytes will always 19310generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} 19311if desired. The following section contains additional 19312details regarding the issue of byte ordering. 19313 19314@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 19315@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{286}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{287} 19316@section Effect of Bit_Order on Byte Ordering 19317 19318 19319@geindex byte ordering 19320 19321@geindex ordering 19322@geindex of bytes 19323 19324In this section we will review the effect of the @code{Bit_Order} attribute 19325definition clause on byte ordering. Briefly, it has no effect at all, but 19326a detailed example will be helpful. Before giving this 19327example, let us review the precise 19328definition of the effect of defining @code{Bit_Order}. The effect of a 19329non-standard bit order is described in section 13.5.3 of the Ada 19330Reference Manual: 19331 19332@quotation 19333 19334"2 A bit ordering is a method of interpreting the meaning of 19335the storage place attributes." 19336@end quotation 19337 19338To understand the precise definition of storage place attributes in 19339this context, we visit section 13.5.1 of the manual: 19340 19341@quotation 19342 19343"13 A record_representation_clause (without the mod_clause) 19344specifies the layout. The storage place attributes (see 13.5.2) 19345are taken from the values of the position, first_bit, and last_bit 19346expressions after normalizing those values so that first_bit is 19347less than Storage_Unit." 19348@end quotation 19349 19350The critical point here is that storage places are taken from 19351the values after normalization, not before. So the @code{Bit_Order} 19352interpretation applies to normalized values. The interpretation 19353is described in the later part of the 13.5.3 paragraph: 19354 19355@quotation 19356 19357"2 A bit ordering is a method of interpreting the meaning of 19358the storage place attributes. High_Order_First (known in the 19359vernacular as 'big endian') means that the first bit of a 19360storage element (bit 0) is the most significant bit (interpreting 19361the sequence of bits that represent a component as an unsigned 19362integer value). Low_Order_First (known in the vernacular as 19363'little endian') means the opposite: the first bit is the 19364least significant." 19365@end quotation 19366 19367Note that the numbering is with respect to the bits of a storage 19368unit. In other words, the specification affects only the numbering 19369of bits within a single storage unit. 19370 19371We can make the effect clearer by giving an example. 19372 19373Suppose that we have an external device which presents two bytes, the first 19374byte presented, which is the first (low addressed byte) of the two byte 19375record is called Master, and the second byte is called Slave. 19376 19377The left most (most significant bit is called Control for each byte, and 19378the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost 19379(least significant) bit. 19380 19381On a big-endian machine, we can write the following representation clause 19382 19383@example 19384type Data is record 19385 Master_Control : Bit; 19386 Master_V1 : Bit; 19387 Master_V2 : Bit; 19388 Master_V3 : Bit; 19389 Master_V4 : Bit; 19390 Master_V5 : Bit; 19391 Master_V6 : Bit; 19392 Master_V7 : Bit; 19393 Slave_Control : Bit; 19394 Slave_V1 : Bit; 19395 Slave_V2 : Bit; 19396 Slave_V3 : Bit; 19397 Slave_V4 : Bit; 19398 Slave_V5 : Bit; 19399 Slave_V6 : Bit; 19400 Slave_V7 : Bit; 19401end record; 19402 19403for Data use record 19404 Master_Control at 0 range 0 .. 0; 19405 Master_V1 at 0 range 1 .. 1; 19406 Master_V2 at 0 range 2 .. 2; 19407 Master_V3 at 0 range 3 .. 3; 19408 Master_V4 at 0 range 4 .. 4; 19409 Master_V5 at 0 range 5 .. 5; 19410 Master_V6 at 0 range 6 .. 6; 19411 Master_V7 at 0 range 7 .. 7; 19412 Slave_Control at 1 range 0 .. 0; 19413 Slave_V1 at 1 range 1 .. 1; 19414 Slave_V2 at 1 range 2 .. 2; 19415 Slave_V3 at 1 range 3 .. 3; 19416 Slave_V4 at 1 range 4 .. 4; 19417 Slave_V5 at 1 range 5 .. 5; 19418 Slave_V6 at 1 range 6 .. 6; 19419 Slave_V7 at 1 range 7 .. 7; 19420end record; 19421@end example 19422 19423Now if we move this to a little endian machine, then the bit ordering within 19424the byte is backwards, so we have to rewrite the record rep clause as: 19425 19426@example 19427for Data use record 19428 Master_Control at 0 range 7 .. 7; 19429 Master_V1 at 0 range 6 .. 6; 19430 Master_V2 at 0 range 5 .. 5; 19431 Master_V3 at 0 range 4 .. 4; 19432 Master_V4 at 0 range 3 .. 3; 19433 Master_V5 at 0 range 2 .. 2; 19434 Master_V6 at 0 range 1 .. 1; 19435 Master_V7 at 0 range 0 .. 0; 19436 Slave_Control at 1 range 7 .. 7; 19437 Slave_V1 at 1 range 6 .. 6; 19438 Slave_V2 at 1 range 5 .. 5; 19439 Slave_V3 at 1 range 4 .. 4; 19440 Slave_V4 at 1 range 3 .. 3; 19441 Slave_V5 at 1 range 2 .. 2; 19442 Slave_V6 at 1 range 1 .. 1; 19443 Slave_V7 at 1 range 0 .. 0; 19444end record; 19445@end example 19446 19447It is a nuisance to have to rewrite the clause, especially if 19448the code has to be maintained on both machines. However, 19449this is a case that we can handle with the 19450@code{Bit_Order} attribute if it is implemented. 19451Note that the implementation is not required on byte addressed 19452machines, but it is indeed implemented in GNAT. 19453This means that we can simply use the 19454first record clause, together with the declaration 19455 19456@example 19457for Data'Bit_Order use High_Order_First; 19458@end example 19459 19460and the effect is what is desired, namely the layout is exactly the same, 19461independent of whether the code is compiled on a big-endian or little-endian 19462machine. 19463 19464The important point to understand is that byte ordering is not affected. 19465A @code{Bit_Order} attribute definition never affects which byte a field 19466ends up in, only where it ends up in that byte. 19467To make this clear, let us rewrite the record rep clause of the previous 19468example as: 19469 19470@example 19471for Data'Bit_Order use High_Order_First; 19472for Data use record 19473 Master_Control at 0 range 0 .. 0; 19474 Master_V1 at 0 range 1 .. 1; 19475 Master_V2 at 0 range 2 .. 2; 19476 Master_V3 at 0 range 3 .. 3; 19477 Master_V4 at 0 range 4 .. 4; 19478 Master_V5 at 0 range 5 .. 5; 19479 Master_V6 at 0 range 6 .. 6; 19480 Master_V7 at 0 range 7 .. 7; 19481 Slave_Control at 0 range 8 .. 8; 19482 Slave_V1 at 0 range 9 .. 9; 19483 Slave_V2 at 0 range 10 .. 10; 19484 Slave_V3 at 0 range 11 .. 11; 19485 Slave_V4 at 0 range 12 .. 12; 19486 Slave_V5 at 0 range 13 .. 13; 19487 Slave_V6 at 0 range 14 .. 14; 19488 Slave_V7 at 0 range 15 .. 15; 19489end record; 19490@end example 19491 19492This is exactly equivalent to saying (a repeat of the first example): 19493 19494@example 19495for Data'Bit_Order use High_Order_First; 19496for Data use record 19497 Master_Control at 0 range 0 .. 0; 19498 Master_V1 at 0 range 1 .. 1; 19499 Master_V2 at 0 range 2 .. 2; 19500 Master_V3 at 0 range 3 .. 3; 19501 Master_V4 at 0 range 4 .. 4; 19502 Master_V5 at 0 range 5 .. 5; 19503 Master_V6 at 0 range 6 .. 6; 19504 Master_V7 at 0 range 7 .. 7; 19505 Slave_Control at 1 range 0 .. 0; 19506 Slave_V1 at 1 range 1 .. 1; 19507 Slave_V2 at 1 range 2 .. 2; 19508 Slave_V3 at 1 range 3 .. 3; 19509 Slave_V4 at 1 range 4 .. 4; 19510 Slave_V5 at 1 range 5 .. 5; 19511 Slave_V6 at 1 range 6 .. 6; 19512 Slave_V7 at 1 range 7 .. 7; 19513end record; 19514@end example 19515 19516Why are they equivalent? Well take a specific field, the @code{Slave_V2} 19517field. The storage place attributes are obtained by normalizing the 19518values given so that the @code{First_Bit} value is less than 8. After 19519normalizing the values (0,10,10) we get (1,2,2) which is exactly what 19520we specified in the other case. 19521 19522Now one might expect that the @code{Bit_Order} attribute might affect 19523bit numbering within the entire record component (two bytes in this 19524case, thus affecting which byte fields end up in), but that is not 19525the way this feature is defined, it only affects numbering of bits, 19526not which byte they end up in. 19527 19528Consequently it never makes sense to specify a starting bit number 19529greater than 7 (for a byte addressable field) if an attribute 19530definition for @code{Bit_Order} has been given, and indeed it 19531may be actively confusing to specify such a value, so the compiler 19532generates a warning for such usage. 19533 19534If you do need to control byte ordering then appropriate conditional 19535values must be used. If in our example, the slave byte came first on 19536some machines we might write: 19537 19538@example 19539Master_Byte_First constant Boolean := ...; 19540 19541Master_Byte : constant Natural := 19542 1 - Boolean'Pos (Master_Byte_First); 19543Slave_Byte : constant Natural := 19544 Boolean'Pos (Master_Byte_First); 19545 19546for Data'Bit_Order use High_Order_First; 19547for Data use record 19548 Master_Control at Master_Byte range 0 .. 0; 19549 Master_V1 at Master_Byte range 1 .. 1; 19550 Master_V2 at Master_Byte range 2 .. 2; 19551 Master_V3 at Master_Byte range 3 .. 3; 19552 Master_V4 at Master_Byte range 4 .. 4; 19553 Master_V5 at Master_Byte range 5 .. 5; 19554 Master_V6 at Master_Byte range 6 .. 6; 19555 Master_V7 at Master_Byte range 7 .. 7; 19556 Slave_Control at Slave_Byte range 0 .. 0; 19557 Slave_V1 at Slave_Byte range 1 .. 1; 19558 Slave_V2 at Slave_Byte range 2 .. 2; 19559 Slave_V3 at Slave_Byte range 3 .. 3; 19560 Slave_V4 at Slave_Byte range 4 .. 4; 19561 Slave_V5 at Slave_Byte range 5 .. 5; 19562 Slave_V6 at Slave_Byte range 6 .. 6; 19563 Slave_V7 at Slave_Byte range 7 .. 7; 19564end record; 19565@end example 19566 19567Now to switch between machines, all that is necessary is 19568to set the boolean constant @code{Master_Byte_First} in 19569an appropriate manner. 19570 19571@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 19572@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{288}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{289} 19573@section Pragma Pack for Arrays 19574 19575 19576@geindex Pragma Pack (for arrays) 19577 19578Pragma @code{Pack} applied to an array has an effect that depends upon whether the 19579component type is @emph{packable}. For a component type to be @emph{packable}, it must 19580be one of the following cases: 19581 19582 19583@itemize * 19584 19585@item 19586Any elementary type. 19587 19588@item 19589Any small packed array type with a static size. 19590 19591@item 19592Any small simple record type with a static size. 19593@end itemize 19594 19595For all these cases, if the component subtype size is in the range 195961 through 64, then the effect of the pragma @code{Pack} is exactly as though a 19597component size were specified giving the component subtype size. 19598 19599All other types are non-packable, they occupy an integral number of storage 19600units and the only effect of pragma Pack is to remove alignment gaps. 19601 19602For example if we have: 19603 19604@example 19605type r is range 0 .. 17; 19606 19607type ar is array (1 .. 8) of r; 19608pragma Pack (ar); 19609@end example 19610 19611Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, 19612and the size of the array @code{ar} will be exactly 40 bits). 19613 19614Note that in some cases this rather fierce approach to packing can produce 19615unexpected effects. For example, in Ada 95 and Ada 2005, 19616subtype @code{Natural} typically has a size of 31, meaning that if you 19617pack an array of @code{Natural}, you get 31-bit 19618close packing, which saves a few bits, but results in far less efficient 19619access. Since many other Ada compilers will ignore such a packing request, 19620GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 19621might not be what is intended. You can easily remove this warning by 19622using an explicit @code{Component_Size} setting instead, which never generates 19623a warning, since the intention of the programmer is clear in this case. 19624 19625GNAT treats packed arrays in one of two ways. If the size of the array is 19626known at compile time and is less than 64 bits, then internally the array 19627is represented as a single modular type, of exactly the appropriate number 19628of bits. If the length is greater than 63 bits, or is not known at compile 19629time, then the packed array is represented as an array of bytes, and the 19630length is always a multiple of 8 bits. 19631 19632Note that to represent a packed array as a modular type, the alignment must 19633be suitable for the modular type involved. For example, on typical machines 19634a 32-bit packed array will be represented by a 32-bit modular integer with 19635an alignment of four bytes. If you explicitly override the default alignment 19636with an alignment clause that is too small, the modular representation 19637cannot be used. For example, consider the following set of declarations: 19638 19639@example 19640type R is range 1 .. 3; 19641type S is array (1 .. 31) of R; 19642for S'Component_Size use 2; 19643for S'Size use 62; 19644for S'Alignment use 1; 19645@end example 19646 19647If the alignment clause were not present, then a 62-bit modular 19648representation would be chosen (typically with an alignment of 4 or 8 19649bytes depending on the target). But the default alignment is overridden 19650with the explicit alignment clause. This means that the modular 19651representation cannot be used, and instead the array of bytes 19652representation must be used, meaning that the length must be a multiple 19653of 8. Thus the above set of declarations will result in a diagnostic 19654rejecting the size clause and noting that the minimum size allowed is 64. 19655 19656@geindex Pragma Pack (for type Natural) 19657 19658@geindex Pragma Pack warning 19659 19660One special case that is worth noting occurs when the base type of the 19661component size is 8/16/32 and the subtype is one bit less. Notably this 19662occurs with subtype @code{Natural}. Consider: 19663 19664@example 19665type Arr is array (1 .. 32) of Natural; 19666pragma Pack (Arr); 19667@end example 19668 19669In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 19670since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 19671Ada 83 compilers did not attempt 31 bit packing. 19672 19673In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 19674GNAT really does pack 31-bit subtype to 31 bits. This may result in a 19675substantial unintended performance penalty when porting legacy Ada 83 code. 19676To help prevent this, GNAT generates a warning in such cases. If you really 19677want 31 bit packing in a case like this, you can set the component size 19678explicitly: 19679 19680@example 19681type Arr is array (1 .. 32) of Natural; 19682for Arr'Component_Size use 31; 19683@end example 19684 19685Here 31-bit packing is achieved as required, and no warning is generated, 19686since in this case the programmer intention is clear. 19687 19688@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 19689@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28a}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28b} 19690@section Pragma Pack for Records 19691 19692 19693@geindex Pragma Pack (for records) 19694 19695Pragma @code{Pack} applied to a record will pack the components to reduce 19696wasted space from alignment gaps and by reducing the amount of space 19697taken by components. We distinguish between @emph{packable} components and 19698@emph{non-packable} components. 19699Components of the following types are considered packable: 19700 19701 19702@itemize * 19703 19704@item 19705Components of an elementary type are packable unless they are aliased, 19706independent, or of an atomic type. 19707 19708@item 19709Small packed arrays, where the size is statically known, are represented 19710internally as modular integers, and so they are also packable. 19711 19712@item 19713Small simple records, where the size is statically known, are also packable. 19714@end itemize 19715 19716For all these cases, if the @code{'Size} value is in the range 1 through 64, the 19717components occupy the exact number of bits corresponding to this value 19718and are packed with no padding bits, i.e. they can start on an arbitrary 19719bit boundary. 19720 19721All other types are non-packable, they occupy an integral number of storage 19722units and the only effect of pragma @code{Pack} is to remove alignment gaps. 19723 19724For example, consider the record 19725 19726@example 19727type Rb1 is array (1 .. 13) of Boolean; 19728pragma Pack (Rb1); 19729 19730type Rb2 is array (1 .. 65) of Boolean; 19731pragma Pack (Rb2); 19732 19733type AF is new Float with Atomic; 19734 19735type X2 is record 19736 L1 : Boolean; 19737 L2 : Duration; 19738 L3 : AF; 19739 L4 : Boolean; 19740 L5 : Rb1; 19741 L6 : Rb2; 19742end record; 19743pragma Pack (X2); 19744@end example 19745 19746The representation for the record @code{X2} is as follows: 19747 19748@example 19749for X2'Size use 224; 19750for X2 use record 19751 L1 at 0 range 0 .. 0; 19752 L2 at 0 range 1 .. 64; 19753 L3 at 12 range 0 .. 31; 19754 L4 at 16 range 0 .. 0; 19755 L5 at 16 range 1 .. 13; 19756 L6 at 18 range 0 .. 71; 19757end record; 19758@end example 19759 19760Studying this example, we see that the packable fields @code{L1} 19761and @code{L2} are 19762of length equal to their sizes, and placed at specific bit boundaries (and 19763not byte boundaries) to 19764eliminate padding. But @code{L3} is of a non-packable float type (because 19765it is aliased), so it is on the next appropriate alignment boundary. 19766 19767The next two fields are fully packable, so @code{L4} and @code{L5} are 19768minimally packed with no gaps. However, type @code{Rb2} is a packed 19769array that is longer than 64 bits, so it is itself non-packable. Thus 19770the @code{L6} field is aligned to the next byte boundary, and takes an 19771integral number of bytes, i.e., 72 bits. 19772 19773@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19774@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28c}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{28d} 19775@section Record Representation Clauses 19776 19777 19778@geindex Record Representation Clause 19779 19780Record representation clauses may be given for all record types, including 19781types obtained by record extension. Component clauses are allowed for any 19782static component. The restrictions on component clauses depend on the type 19783of the component. 19784 19785@geindex Component Clause 19786 19787For all components of an elementary type, the only restriction on component 19788clauses is that the size must be at least the @code{'Size} value of the type 19789(actually the Value_Size). There are no restrictions due to alignment, 19790and such components may freely cross storage boundaries. 19791 19792Packed arrays with a size up to and including 64 bits are represented 19793internally using a modular type with the appropriate number of bits, and 19794thus the same lack of restriction applies. For example, if you declare: 19795 19796@example 19797type R is array (1 .. 49) of Boolean; 19798pragma Pack (R); 19799for R'Size use 49; 19800@end example 19801 19802then a component clause for a component of type @code{R} may start on any 19803specified bit boundary, and may specify a value of 49 bits or greater. 19804 19805For packed bit arrays that are longer than 64 bits, there are two 19806cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 19807including the important case of single bits or boolean values, then 19808there are no limitations on placement of such components, and they 19809may start and end at arbitrary bit boundaries. 19810 19811If the component size is not a power of 2 (e.g., 3 or 5), then 19812an array of this type longer than 64 bits must always be placed on 19813on a storage unit (byte) boundary and occupy an integral number 19814of storage units (bytes). Any component clause that does not 19815meet this requirement will be rejected. 19816 19817Any aliased component, or component of an aliased type, must 19818have its normal alignment and size. A component clause that 19819does not meet this requirement will be rejected. 19820 19821The tag field of a tagged type always occupies an address sized field at 19822the start of the record. No component clause may attempt to overlay this 19823tag. When a tagged type appears as a component, the tag field must have 19824proper alignment 19825 19826In the case of a record extension @code{T1}, of a type @code{T}, no component clause applied 19827to the type @code{T1} can specify a storage location that would overlap the first 19828@code{T'Size} bytes of the record. 19829 19830For all other component types, including non-bit-packed arrays, 19831the component can be placed at an arbitrary bit boundary, 19832so for example, the following is permitted: 19833 19834@example 19835type R is array (1 .. 10) of Boolean; 19836for R'Size use 80; 19837 19838type Q is record 19839 G, H : Boolean; 19840 L, M : R; 19841end record; 19842 19843for Q use record 19844 G at 0 range 0 .. 0; 19845 H at 0 range 1 .. 1; 19846 L at 0 range 2 .. 81; 19847 R at 0 range 82 .. 161; 19848end record; 19849@end example 19850 19851@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19852@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{28e}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{28f} 19853@section Handling of Records with Holes 19854 19855 19856@geindex Handling of Records with Holes 19857 19858As a result of alignment considerations, records may contain "holes" 19859or gaps 19860which do not correspond to the data bits of any of the components. 19861Record representation clauses can also result in holes in records. 19862 19863GNAT does not attempt to clear these holes, so in record objects, 19864they should be considered to hold undefined rubbish. The generated 19865equality routine just tests components so does not access these 19866undefined bits, and assignment and copy operations may or may not 19867preserve the contents of these holes (for assignments, the holes 19868in the target will in practice contain either the bits that are 19869present in the holes in the source, or the bits that were present 19870in the target before the assignment). 19871 19872If it is necessary to ensure that holes in records have all zero 19873bits, then record objects for which this initialization is desired 19874should be explicitly set to all zero values using Unchecked_Conversion 19875or address overlays. For example 19876 19877@example 19878type HRec is record 19879 C : Character; 19880 I : Integer; 19881end record; 19882@end example 19883 19884On typical machines, integers need to be aligned on a four-byte 19885boundary, resulting in three bytes of undefined rubbish following 19886the 8-bit field for C. To ensure that the hole in a variable of 19887type HRec is set to all zero bits, 19888you could for example do: 19889 19890@example 19891type Base is record 19892 Dummy1, Dummy2 : Integer := 0; 19893end record; 19894 19895BaseVar : Base; 19896RealVar : Hrec; 19897for RealVar'Address use BaseVar'Address; 19898@end example 19899 19900Now the 8-bytes of the value of RealVar start out containing all zero 19901bits. A safer approach is to just define dummy fields, avoiding the 19902holes, as in: 19903 19904@example 19905type HRec is record 19906 C : Character; 19907 Dummy1 : Short_Short_Integer := 0; 19908 Dummy2 : Short_Short_Integer := 0; 19909 Dummy3 : Short_Short_Integer := 0; 19910 I : Integer; 19911end record; 19912@end example 19913 19914And to make absolutely sure that the intent of this is followed, you 19915can use representation clauses: 19916 19917@example 19918for Hrec use record 19919 C at 0 range 0 .. 7; 19920 Dummy1 at 1 range 0 .. 7; 19921 Dummy2 at 2 range 0 .. 7; 19922 Dummy3 at 3 range 0 .. 7; 19923 I at 4 range 0 .. 31; 19924end record; 19925for Hrec'Size use 64; 19926@end example 19927 19928@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 19929@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{290}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{291} 19930@section Enumeration Clauses 19931 19932 19933The only restriction on enumeration clauses is that the range of values 19934must be representable. For the signed case, if one or more of the 19935representation values are negative, all values must be in the range: 19936 19937@example 19938System.Min_Int .. System.Max_Int 19939@end example 19940 19941For the unsigned case, where all values are nonnegative, the values must 19942be in the range: 19943 19944@example 199450 .. System.Max_Binary_Modulus; 19946@end example 19947 19948A @emph{confirming} representation clause is one in which the values range 19949from 0 in sequence, i.e., a clause that confirms the default representation 19950for an enumeration type. 19951Such a confirming representation 19952is permitted by these rules, and is specially recognized by the compiler so 19953that no extra overhead results from the use of such a clause. 19954 19955If an array has an index type which is an enumeration type to which an 19956enumeration clause has been applied, then the array is stored in a compact 19957manner. Consider the declarations: 19958 19959@example 19960type r is (A, B, C); 19961for r use (A => 1, B => 5, C => 10); 19962type t is array (r) of Character; 19963@end example 19964 19965The array type t corresponds to a vector with exactly three elements and 19966has a default size equal to @code{3*Character'Size}. This ensures efficient 19967use of space, but means that accesses to elements of the array will incur 19968the overhead of converting representation values to the corresponding 19969positional values, (i.e., the value delivered by the @code{Pos} attribute). 19970 19971@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 19972@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{292}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{293} 19973@section Address Clauses 19974 19975 19976@geindex Address Clause 19977 19978The reference manual allows a general restriction on representation clauses, 19979as found in RM 13.1(22): 19980 19981@quotation 19982 19983"An implementation need not support representation 19984items containing nonstatic expressions, except that 19985an implementation should support a representation item 19986for a given entity if each nonstatic expression in the 19987representation item is a name that statically denotes 19988a constant declared before the entity." 19989@end quotation 19990 19991In practice this is applicable only to address clauses, since this is the 19992only case in which a nonstatic expression is permitted by the syntax. As 19993the AARM notes in sections 13.1 (22.a-22.h): 19994 19995@quotation 19996 1999722.a Reason: This is to avoid the following sort of thing: 19998 1999922.b X : Integer := F(...); 20000Y : Address := G(...); 20001for X'Address use Y; 20002 2000322.c In the above, we have to evaluate the 20004initialization expression for X before we 20005know where to put the result. This seems 20006like an unreasonable implementation burden. 20007 2000822.d The above code should instead be written 20009like this: 20010 2001122.e Y : constant Address := G(...); 20012X : Integer := F(...); 20013for X'Address use Y; 20014 2001522.f This allows the expression 'Y' to be safely 20016evaluated before X is created. 20017 2001822.g The constant could be a formal parameter of mode in. 20019 2002022.h An implementation can support other nonstatic 20021expressions if it wants to. Expressions of type 20022Address are hardly ever static, but their value 20023might be known at compile time anyway in many 20024cases. 20025@end quotation 20026 20027GNAT does indeed permit many additional cases of nonstatic expressions. In 20028particular, if the type involved is elementary there are no restrictions 20029(since in this case, holding a temporary copy of the initialization value, 20030if one is present, is inexpensive). In addition, if there is no implicit or 20031explicit initialization, then there are no restrictions. GNAT will reject 20032only the case where all three of these conditions hold: 20033 20034 20035@itemize * 20036 20037@item 20038The type of the item is non-elementary (e.g., a record or array). 20039 20040@item 20041There is explicit or implicit initialization required for the object. 20042Note that access values are always implicitly initialized. 20043 20044@item 20045The address value is nonstatic. Here GNAT is more permissive than the 20046RM, and allows the address value to be the address of a previously declared 20047stand-alone variable, as long as it does not itself have an address clause. 20048 20049@example 20050Anchor : Some_Initialized_Type; 20051Overlay : Some_Initialized_Type; 20052for Overlay'Address use Anchor'Address; 20053@end example 20054 20055However, the prefix of the address clause cannot be an array component, or 20056a component of a discriminated record. 20057@end itemize 20058 20059As noted above in section 22.h, address values are typically nonstatic. In 20060particular the To_Address function, even if applied to a literal value, is 20061a nonstatic function call. To avoid this minor annoyance, GNAT provides 20062the implementation defined attribute 'To_Address. The following two 20063expressions have identical values: 20064 20065@geindex Attribute 20066 20067@geindex To_Address 20068 20069@example 20070To_Address (16#1234_0000#) 20071System'To_Address (16#1234_0000#); 20072@end example 20073 20074except that the second form is considered to be a static expression, and 20075thus when used as an address clause value is always permitted. 20076 20077Additionally, GNAT treats as static an address clause that is an 20078unchecked_conversion of a static integer value. This simplifies the porting 20079of legacy code, and provides a portable equivalent to the GNAT attribute 20080@code{To_Address}. 20081 20082Another issue with address clauses is the interaction with alignment 20083requirements. When an address clause is given for an object, the address 20084value must be consistent with the alignment of the object (which is usually 20085the same as the alignment of the type of the object). If an address clause 20086is given that specifies an inappropriately aligned address value, then the 20087program execution is erroneous. 20088 20089Since this source of erroneous behavior can have unfortunate effects on 20090machines with strict alignment requirements, GNAT 20091checks (at compile time if possible, generating a warning, or at execution 20092time with a run-time check) that the alignment is appropriate. If the 20093run-time check fails, then @code{Program_Error} is raised. This run-time 20094check is suppressed if range checks are suppressed, or if the special GNAT 20095check Alignment_Check is suppressed, or if 20096@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 20097suppressed by default on non-strict alignment machines (such as the x86). 20098 20099Finally, GNAT does not permit overlaying of objects of class-wide types. In 20100most cases, the compiler can detect an attempt at such overlays and will 20101generate a warning at compile time and a Program_Error exception at run time. 20102 20103@geindex Export 20104 20105An address clause cannot be given for an exported object. More 20106understandably the real restriction is that objects with an address 20107clause cannot be exported. This is because such variables are not 20108defined by the Ada program, so there is no external object to export. 20109 20110@geindex Import 20111 20112It is permissible to give an address clause and a pragma Import for the 20113same object. In this case, the variable is not really defined by the 20114Ada program, so there is no external symbol to be linked. The link name 20115and the external name are ignored in this case. The reason that we allow this 20116combination is that it provides a useful idiom to avoid unwanted 20117initializations on objects with address clauses. 20118 20119When an address clause is given for an object that has implicit or 20120explicit initialization, then by default initialization takes place. This 20121means that the effect of the object declaration is to overwrite the 20122memory at the specified address. This is almost always not what the 20123programmer wants, so GNAT will output a warning: 20124 20125@example 20126with System; 20127package G is 20128 type R is record 20129 M : Integer := 0; 20130 end record; 20131 20132 Ext : R; 20133 for Ext'Address use System'To_Address (16#1234_1234#); 20134 | 20135>>> warning: implicit initialization of "Ext" may 20136 modify overlaid storage 20137>>> warning: use pragma Import for "Ext" to suppress 20138 initialization (RM B(24)) 20139 20140end G; 20141@end example 20142 20143As indicated by the warning message, the solution is to use a (dummy) pragma 20144Import to suppress this initialization. The pragma tell the compiler that the 20145object is declared and initialized elsewhere. The following package compiles 20146without warnings (and the initialization is suppressed): 20147 20148@example 20149with System; 20150package G is 20151 type R is record 20152 M : Integer := 0; 20153 end record; 20154 20155 Ext : R; 20156 for Ext'Address use System'To_Address (16#1234_1234#); 20157 pragma Import (Ada, Ext); 20158end G; 20159@end example 20160 20161A final issue with address clauses involves their use for overlaying 20162variables, as in the following example: 20163 20164@geindex Overlaying of objects 20165 20166@example 20167A : Integer; 20168B : Integer; 20169for B'Address use A'Address; 20170@end example 20171 20172or alternatively, using the form recommended by the RM: 20173 20174@example 20175A : Integer; 20176Addr : constant Address := A'Address; 20177B : Integer; 20178for B'Address use Addr; 20179@end example 20180 20181In both of these cases, @code{A} and @code{B} become aliased to one another 20182via the address clause. This use of address clauses to overlay 20183variables, achieving an effect similar to unchecked conversion 20184was erroneous in Ada 83, but in Ada 95 and Ada 2005 20185the effect is implementation defined. Furthermore, the 20186Ada RM specifically recommends that in a situation 20187like this, @code{B} should be subject to the following 20188implementation advice (RM 13.3(19)): 20189 20190@quotation 20191 20192"19 If the Address of an object is specified, or it is imported 20193or exported, then the implementation should not perform 20194optimizations based on assumptions of no aliases." 20195@end quotation 20196 20197GNAT follows this recommendation, and goes further by also applying 20198this recommendation to the overlaid variable (@code{A} in the above example) 20199in this case. This means that the overlay works "as expected", in that 20200a modification to one of the variables will affect the value of the other. 20201 20202More generally, GNAT interprets this recommendation conservatively for 20203address clauses: in the cases other than overlays, it considers that the 20204object is effectively subject to pragma @code{Volatile} and implements the 20205associated semantics. 20206 20207Note that when address clause overlays are used in this way, there is an 20208issue of unintentional initialization, as shown by this example: 20209 20210@example 20211package Overwrite_Record is 20212 type R is record 20213 A : Character := 'C'; 20214 B : Character := 'A'; 20215 end record; 20216 X : Short_Integer := 3; 20217 Y : R; 20218 for Y'Address use X'Address; 20219 | 20220>>> warning: default initialization of "Y" may 20221 modify "X", use pragma Import for "Y" to 20222 suppress initialization (RM B.1(24)) 20223 20224end Overwrite_Record; 20225@end example 20226 20227Here the default initialization of @code{Y} will clobber the value 20228of @code{X}, which justifies the warning. The warning notes that 20229this effect can be eliminated by adding a @code{pragma Import} 20230which suppresses the initialization: 20231 20232@example 20233package Overwrite_Record is 20234 type R is record 20235 A : Character := 'C'; 20236 B : Character := 'A'; 20237 end record; 20238 X : Short_Integer := 3; 20239 Y : R; 20240 for Y'Address use X'Address; 20241 pragma Import (Ada, Y); 20242end Overwrite_Record; 20243@end example 20244 20245Note that the use of @code{pragma Initialize_Scalars} may cause variables to 20246be initialized when they would not otherwise have been in the absence 20247of the use of this pragma. This may cause an overlay to have this 20248unintended clobbering effect. The compiler avoids this for scalar 20249types, but not for composite objects (where in general the effect 20250of @code{Initialize_Scalars} is part of the initialization routine 20251for the composite object: 20252 20253@example 20254pragma Initialize_Scalars; 20255with Ada.Text_IO; use Ada.Text_IO; 20256procedure Overwrite_Array is 20257 type Arr is array (1 .. 5) of Integer; 20258 X : Arr := (others => 1); 20259 A : Arr; 20260 for A'Address use X'Address; 20261 | 20262>>> warning: default initialization of "A" may 20263 modify "X", use pragma Import for "A" to 20264 suppress initialization (RM B.1(24)) 20265 20266begin 20267 if X /= Arr'(others => 1) then 20268 Put_Line ("X was clobbered"); 20269 else 20270 Put_Line ("X was not clobbered"); 20271 end if; 20272end Overwrite_Array; 20273@end example 20274 20275The above program generates the warning as shown, and at execution 20276time, prints @code{X was clobbered}. If the @code{pragma Import} is 20277added as suggested: 20278 20279@example 20280pragma Initialize_Scalars; 20281with Ada.Text_IO; use Ada.Text_IO; 20282procedure Overwrite_Array is 20283 type Arr is array (1 .. 5) of Integer; 20284 X : Arr := (others => 1); 20285 A : Arr; 20286 for A'Address use X'Address; 20287 pragma Import (Ada, A); 20288begin 20289 if X /= Arr'(others => 1) then 20290 Put_Line ("X was clobbered"); 20291 else 20292 Put_Line ("X was not clobbered"); 20293 end if; 20294end Overwrite_Array; 20295@end example 20296 20297then the program compiles without the warning and when run will generate 20298the output @code{X was not clobbered}. 20299 20300@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 20301@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{294}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{295} 20302@section Use of Address Clauses for Memory-Mapped I/O 20303 20304 20305@geindex Memory-mapped I/O 20306 20307A common pattern is to use an address clause to map an atomic variable to 20308a location in memory that corresponds to a memory-mapped I/O operation or 20309operations, for example: 20310 20311@example 20312type Mem_Word is record 20313 A,B,C,D : Byte; 20314end record; 20315pragma Atomic (Mem_Word); 20316for Mem_Word_Size use 32; 20317 20318Mem : Mem_Word; 20319for Mem'Address use some-address; 20320... 20321Temp := Mem; 20322Temp.A := 32; 20323Mem := Temp; 20324@end example 20325 20326For a full access (reference or modification) of the variable (Mem) in this 20327case, as in the above examples, GNAT guarantees that the entire atomic word 20328will be accessed, in accordance with the RM C.6(15) clause. 20329 20330A problem arises with a component access such as: 20331 20332@example 20333Mem.A := 32; 20334@end example 20335 20336Note that the component A is not declared as atomic. This means that it is 20337not clear what this assignment means. It could correspond to full word read 20338and write as given in the first example, or on architectures that supported 20339such an operation it might be a single byte store instruction. The RM does 20340not have anything to say in this situation, and GNAT does not make any 20341guarantee. The code generated may vary from target to target. GNAT will issue 20342a warning in such a case: 20343 20344@example 20345Mem.A := 32; 20346| 20347>>> warning: access to non-atomic component of atomic array, 20348 may cause unexpected accesses to atomic object 20349@end example 20350 20351It is best to be explicit in this situation, by either declaring the 20352components to be atomic if you want the byte store, or explicitly writing 20353the full word access sequence if that is what the hardware requires. 20354Alternatively, if the full word access sequence is required, GNAT also 20355provides the pragma @code{Volatile_Full_Access} which can be used in lieu of 20356pragma @code{Atomic} and will give the additional guarantee. 20357 20358@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 20359@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{296}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{297} 20360@section Effect of Convention on Representation 20361 20362 20363@geindex Convention 20364@geindex effect on representation 20365 20366Normally the specification of a foreign language convention for a type or 20367an object has no effect on the chosen representation. In particular, the 20368representation chosen for data in GNAT generally meets the standard system 20369conventions, and for example records are laid out in a manner that is 20370consistent with C. This means that specifying convention C (for example) 20371has no effect. 20372 20373There are four exceptions to this general rule: 20374 20375 20376@itemize * 20377 20378@item 20379@emph{Convention Fortran and array subtypes}. 20380 20381If pragma Convention Fortran is specified for an array subtype, then in 20382accordance with the implementation advice in section 3.6.2(11) of the 20383Ada Reference Manual, the array will be stored in a Fortran-compatible 20384column-major manner, instead of the normal default row-major order. 20385 20386@item 20387@emph{Convention C and enumeration types} 20388 20389GNAT normally stores enumeration types in 8, 16, or 32 bits as required 20390to accommodate all values of the type. For example, for the enumeration 20391type declared by: 20392 20393@example 20394type Color is (Red, Green, Blue); 20395@end example 20396 203978 bits is sufficient to store all values of the type, so by default, objects 20398of type @code{Color} will be represented using 8 bits. However, normal C 20399convention is to use 32 bits for all enum values in C, since enum values 20400are essentially of type int. If pragma @code{Convention C} is specified for an 20401Ada enumeration type, then the size is modified as necessary (usually to 2040232 bits) to be consistent with the C convention for enum values. 20403 20404Note that this treatment applies only to types. If Convention C is given for 20405an enumeration object, where the enumeration type is not Convention C, then 20406Object_Size bits are allocated. For example, for a normal enumeration type, 20407with less than 256 elements, only 8 bits will be allocated for the object. 20408Since this may be a surprise in terms of what C expects, GNAT will issue a 20409warning in this situation. The warning can be suppressed by giving an explicit 20410size clause specifying the desired size. 20411 20412@item 20413@emph{Convention C/Fortran and Boolean types} 20414 20415In C, the usual convention for boolean values, that is values used for 20416conditions, is that zero represents false, and nonzero values represent 20417true. In Ada, the normal convention is that two specific values, typically 204180/1, are used to represent false/true respectively. 20419 20420Fortran has a similar convention for @code{LOGICAL} values (any nonzero 20421value represents true). 20422 20423To accommodate the Fortran and C conventions, if a pragma Convention specifies 20424C or Fortran convention for a derived Boolean, as in the following example: 20425 20426@example 20427type C_Switch is new Boolean; 20428pragma Convention (C, C_Switch); 20429@end example 20430 20431then the GNAT generated code will treat any nonzero value as true. For truth 20432values generated by GNAT, the conventional value 1 will be used for True, but 20433when one of these values is read, any nonzero value is treated as True. 20434@end itemize 20435 20436@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 20437@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{298}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{299} 20438@section Conventions and Anonymous Access Types 20439 20440 20441@geindex Anonymous access types 20442 20443@geindex Convention for anonymous access types 20444 20445The RM is not entirely clear on convention handling in a number of cases, 20446and in particular, it is not clear on the convention to be given to 20447anonymous access types in general, and in particular what is to be 20448done for the case of anonymous access-to-subprogram. 20449 20450In GNAT, we decide that if an explicit Convention is applied 20451to an object or component, and its type is such an anonymous type, 20452then the convention will apply to this anonymous type as well. This 20453seems to make sense since it is anomolous in any case to have a 20454different convention for an object and its type, and there is clearly 20455no way to explicitly specify a convention for an anonymous type, since 20456it doesn't have a name to specify! 20457 20458Furthermore, we decide that if a convention is applied to a record type, 20459then this convention is inherited by any of its components that are of an 20460anonymous access type which do not have an explicitly specified convention. 20461 20462The following program shows these conventions in action: 20463 20464@example 20465package ConvComp is 20466 type Foo is range 1 .. 10; 20467 type T1 is record 20468 A : access function (X : Foo) return Integer; 20469 B : Integer; 20470 end record; 20471 pragma Convention (C, T1); 20472 20473 type T2 is record 20474 A : access function (X : Foo) return Integer; 20475 pragma Convention (C, A); 20476 B : Integer; 20477 end record; 20478 pragma Convention (COBOL, T2); 20479 20480 type T3 is record 20481 A : access function (X : Foo) return Integer; 20482 pragma Convention (COBOL, A); 20483 B : Integer; 20484 end record; 20485 pragma Convention (C, T3); 20486 20487 type T4 is record 20488 A : access function (X : Foo) return Integer; 20489 B : Integer; 20490 end record; 20491 pragma Convention (COBOL, T4); 20492 20493 function F (X : Foo) return Integer; 20494 pragma Convention (C, F); 20495 20496 function F (X : Foo) return Integer is (13); 20497 20498 TV1 : T1 := (F'Access, 12); -- OK 20499 TV2 : T2 := (F'Access, 13); -- OK 20500 20501 TV3 : T3 := (F'Access, 13); -- ERROR 20502 | 20503>>> subprogram "F" has wrong convention 20504>>> does not match access to subprogram declared at line 17 20505 38. TV4 : T4 := (F'Access, 13); -- ERROR 20506 | 20507>>> subprogram "F" has wrong convention 20508>>> does not match access to subprogram declared at line 24 20509 39. end ConvComp; 20510@end example 20511 20512@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 20513@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29a}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29b} 20514@section Determining the Representations chosen by GNAT 20515 20516 20517@geindex Representation 20518@geindex determination of 20519 20520@geindex -gnatR (gcc) 20521 20522Although the descriptions in this section are intended to be complete, it is 20523often easier to simply experiment to see what GNAT accepts and what the 20524effect is on the layout of types and objects. 20525 20526As required by the Ada RM, if a representation clause is not accepted, then 20527it must be rejected as illegal by the compiler. However, when a 20528representation clause or pragma is accepted, there can still be questions 20529of what the compiler actually does. For example, if a partial record 20530representation clause specifies the location of some components and not 20531others, then where are the non-specified components placed? Or if pragma 20532@code{Pack} is used on a record, then exactly where are the resulting 20533fields placed? The section on pragma @code{Pack} in this chapter can be 20534used to answer the second question, but it is often easier to just see 20535what the compiler does. 20536 20537For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 20538with this option, then the compiler will output information on the actual 20539representations chosen, in a format similar to source representation 20540clauses. For example, if we compile the package: 20541 20542@example 20543package q is 20544 type r (x : boolean) is tagged record 20545 case x is 20546 when True => S : String (1 .. 100); 20547 when False => null; 20548 end case; 20549 end record; 20550 20551 type r2 is new r (false) with record 20552 y2 : integer; 20553 end record; 20554 20555 for r2 use record 20556 y2 at 16 range 0 .. 31; 20557 end record; 20558 20559 type x is record 20560 y : character; 20561 end record; 20562 20563 type x1 is array (1 .. 10) of x; 20564 for x1'component_size use 11; 20565 20566 type ia is access integer; 20567 20568 type Rb1 is array (1 .. 13) of Boolean; 20569 pragma Pack (rb1); 20570 20571 type Rb2 is array (1 .. 65) of Boolean; 20572 pragma Pack (rb2); 20573 20574 type x2 is record 20575 l1 : Boolean; 20576 l2 : Duration; 20577 l3 : Float; 20578 l4 : Boolean; 20579 l5 : Rb1; 20580 l6 : Rb2; 20581 end record; 20582 pragma Pack (x2); 20583end q; 20584@end example 20585 20586using the switch @emph{-gnatR} we obtain the following output: 20587 20588@example 20589Representation information for unit q 20590------------------------------------- 20591 20592for r'Size use ??; 20593for r'Alignment use 4; 20594for r use record 20595 x at 4 range 0 .. 7; 20596 _tag at 0 range 0 .. 31; 20597 s at 5 range 0 .. 799; 20598end record; 20599 20600for r2'Size use 160; 20601for r2'Alignment use 4; 20602for r2 use record 20603 x at 4 range 0 .. 7; 20604 _tag at 0 range 0 .. 31; 20605 _parent at 0 range 0 .. 63; 20606 y2 at 16 range 0 .. 31; 20607end record; 20608 20609for x'Size use 8; 20610for x'Alignment use 1; 20611for x use record 20612 y at 0 range 0 .. 7; 20613end record; 20614 20615for x1'Size use 112; 20616for x1'Alignment use 1; 20617for x1'Component_Size use 11; 20618 20619for rb1'Size use 13; 20620for rb1'Alignment use 2; 20621for rb1'Component_Size use 1; 20622 20623for rb2'Size use 72; 20624for rb2'Alignment use 1; 20625for rb2'Component_Size use 1; 20626 20627for x2'Size use 224; 20628for x2'Alignment use 4; 20629for x2 use record 20630 l1 at 0 range 0 .. 0; 20631 l2 at 0 range 1 .. 64; 20632 l3 at 12 range 0 .. 31; 20633 l4 at 16 range 0 .. 0; 20634 l5 at 16 range 1 .. 13; 20635 l6 at 18 range 0 .. 71; 20636end record; 20637@end example 20638 20639The Size values are actually the Object_Size, i.e., the default size that 20640will be allocated for objects of the type. 20641The @code{??} size for type r indicates that we have a variant record, and the 20642actual size of objects will depend on the discriminant value. 20643 20644The Alignment values show the actual alignment chosen by the compiler 20645for each record or array type. 20646 20647The record representation clause for type r shows where all fields 20648are placed, including the compiler generated tag field (whose location 20649cannot be controlled by the programmer). 20650 20651The record representation clause for the type extension r2 shows all the 20652fields present, including the parent field, which is a copy of the fields 20653of the parent type of r2, i.e., r1. 20654 20655The component size and size clauses for types rb1 and rb2 show 20656the exact effect of pragma @code{Pack} on these arrays, and the record 20657representation clause for type x2 shows how pragma @cite{Pack} affects 20658this record type. 20659 20660In some cases, it may be useful to cut and paste the representation clauses 20661generated by the compiler into the original source to fix and guarantee 20662the actual representation to be used. 20663 20664@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 20665@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{29c}@anchor{gnat_rm/standard_library_routines id1}@anchor{29d} 20666@chapter Standard Library Routines 20667 20668 20669The Ada Reference Manual contains in Annex A a full description of an 20670extensive set of standard library routines that can be used in any Ada 20671program, and which must be provided by all Ada compilers. They are 20672analogous to the standard C library used by C programs. 20673 20674GNAT implements all of the facilities described in annex A, and for most 20675purposes the description in the Ada Reference Manual, or appropriate Ada 20676text book, will be sufficient for making use of these facilities. 20677 20678In the case of the input-output facilities, 20679@ref{f,,The Implementation of Standard I/O}, 20680gives details on exactly how GNAT interfaces to the 20681file system. For the remaining packages, the Ada Reference Manual 20682should be sufficient. The following is a list of the packages included, 20683together with a brief description of the functionality that is provided. 20684 20685For completeness, references are included to other predefined library 20686routines defined in other sections of the Ada Reference Manual (these are 20687cross-indexed from Annex A). For further details see the relevant 20688package declarations in the run-time library. In particular, a few units 20689are not implemented, as marked by the presence of pragma Unimplemented_Unit, 20690and in this case the package declaration contains comments explaining why 20691the unit is not implemented. 20692 20693 20694@table @asis 20695 20696@item @code{Ada} @emph{(A.2)} 20697 20698This is a parent package for all the standard library packages. It is 20699usually included implicitly in your program, and itself contains no 20700useful data or routines. 20701 20702@item @code{Ada.Assertions} @emph{(11.4.2)} 20703 20704@code{Assertions} provides the @code{Assert} subprograms, and also 20705the declaration of the @code{Assertion_Error} exception. 20706 20707@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 20708 20709@code{Asynchronous_Task_Control} provides low level facilities for task 20710synchronization. It is typically not implemented. See package spec for details. 20711 20712@item @code{Ada.Calendar} @emph{(9.6)} 20713 20714@code{Calendar} provides time of day access, and routines for 20715manipulating times and durations. 20716 20717@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 20718 20719This package provides additional arithmetic 20720operations for @code{Calendar}. 20721 20722@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 20723 20724This package provides formatting operations for @code{Calendar}. 20725 20726@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 20727 20728This package provides additional @code{Calendar} facilities 20729for handling time zones. 20730 20731@item @code{Ada.Characters} @emph{(A.3.1)} 20732 20733This is a dummy parent package that contains no useful entities 20734 20735@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 20736 20737This package provides character conversion functions. 20738 20739@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 20740 20741This package provides some basic character handling capabilities, 20742including classification functions for classes of characters (e.g., test 20743for letters, or digits). 20744 20745@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 20746 20747This package includes a complete set of definitions of the characters 20748that appear in type CHARACTER. It is useful for writing programs that 20749will run in international environments. For example, if you want an 20750upper case E with an acute accent in a string, it is often better to use 20751the definition of @code{UC_E_Acute} in this package. Then your program 20752will print in an understandable manner even if your environment does not 20753support these extended characters. 20754 20755@item @code{Ada.Command_Line} @emph{(A.15)} 20756 20757This package provides access to the command line parameters and the name 20758of the current program (analogous to the use of @code{argc} and @code{argv} 20759in C), and also allows the exit status for the program to be set in a 20760system-independent manner. 20761 20762@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20763 20764This package provides text input and output of complex numbers. 20765 20766@item @code{Ada.Containers} @emph{(A.18.1)} 20767 20768A top level package providing a few basic definitions used by all the 20769following specific child packages that provide specific kinds of 20770containers. 20771@end table 20772 20773@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20774 20775@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20776 20777@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20778 20779@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20780 20781@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20782 20783@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20784 20785@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20786 20787@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20788 20789@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20790 20791@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20792 20793@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20794 20795@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20796 20797@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20798 20799@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20800 20801@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20802 20803@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20804 20805@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20806 20807@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20808 20809@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20810 20811@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20812 20813@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20814 20815@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20816 20817@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20818 20819 20820@table @asis 20821 20822@item @code{Ada.Directories} @emph{(A.16)} 20823 20824This package provides operations on directories. 20825 20826@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20827 20828This package provides additional directory operations handling 20829hiearchical file names. 20830 20831@item @code{Ada.Directories.Information} @emph{(A.16)} 20832 20833This is an implementation defined package for additional directory 20834operations, which is not implemented in GNAT. 20835 20836@item @code{Ada.Decimal} @emph{(F.2)} 20837 20838This package provides constants describing the range of decimal numbers 20839implemented, and also a decimal divide routine (analogous to the COBOL 20840verb DIVIDE ... GIVING ... REMAINDER ...) 20841 20842@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20843 20844This package provides input-output using a model of a set of records of 20845fixed-length, containing an arbitrary definite Ada type, indexed by an 20846integer record number. 20847 20848@item @code{Ada.Dispatching} @emph{(D.2.1)} 20849 20850A parent package containing definitions for task dispatching operations. 20851 20852@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20853 20854Not implemented in GNAT. 20855 20856@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20857 20858Not implemented in GNAT. 20859 20860@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20861 20862Not implemented in GNAT. 20863 20864@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20865 20866This package allows the priorities of a task to be adjusted dynamically 20867as the task is running. 20868 20869@item @code{Ada.Environment_Variables} @emph{(A.17)} 20870 20871This package provides facilities for accessing environment variables. 20872 20873@item @code{Ada.Exceptions} @emph{(11.4.1)} 20874 20875This package provides additional information on exceptions, and also 20876contains facilities for treating exceptions as data objects, and raising 20877exceptions with associated messages. 20878 20879@item @code{Ada.Execution_Time} @emph{(D.14)} 20880 20881This package provides CPU clock functionalities. It is not implemented on 20882all targets (see package spec for details). 20883 20884@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20885 20886Not implemented in GNAT. 20887 20888@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'} 20889 20890Not implemented in GNAT. 20891 20892@item @code{Ada.Finalization} @emph{(7.6)} 20893 20894This package contains the declarations and subprograms to support the 20895use of controlled types, providing for automatic initialization and 20896finalization (analogous to the constructors and destructors of C++). 20897 20898@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20899 20900A library level instantiation of Text_IO.Float_IO for type Float. 20901 20902@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 20903 20904A library level instantiation of Wide_Text_IO.Float_IO for type Float. 20905 20906@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 20907 20908A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 20909 20910@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 20911 20912A library level instantiation of Text_IO.Integer_IO for type Integer. 20913 20914@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 20915 20916A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 20917 20918@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 20919 20920A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 20921 20922@item @code{Ada.Interrupts} @emph{(C.3.2)} 20923 20924This package provides facilities for interfacing to interrupts, which 20925includes the set of signals or conditions that can be raised and 20926recognized as interrupts. 20927 20928@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 20929 20930This package provides the set of interrupt names (actually signal 20931or condition names) that can be handled by GNAT. 20932 20933@item @code{Ada.IO_Exceptions} @emph{(A.13)} 20934 20935This package defines the set of exceptions that can be raised by use of 20936the standard IO packages. 20937 20938@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 20939 20940This package provides a generic interface to generalized iterators. 20941 20942@item @code{Ada.Locales} @emph{(A.19)} 20943 20944This package provides declarations providing information (Language 20945and Country) about the current locale. 20946 20947@item @code{Ada.Numerics} 20948 20949This package contains some standard constants and exceptions used 20950throughout the numerics packages. Note that the constants pi and e are 20951defined here, and it is better to use these definitions than rolling 20952your own. 20953 20954@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 20955 20956Provides operations on arrays of complex numbers. 20957 20958@item @code{Ada.Numerics.Complex_Elementary_Functions} 20959 20960Provides the implementation of standard elementary functions (such as 20961log and trigonometric functions) operating on complex numbers using the 20962standard @code{Float} and the @code{Complex} and @code{Imaginary} types 20963created by the package @code{Numerics.Complex_Types}. 20964 20965@item @code{Ada.Numerics.Complex_Types} 20966 20967This is a predefined instantiation of 20968@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 20969build the type @code{Complex} and @code{Imaginary}. 20970 20971@item @code{Ada.Numerics.Discrete_Random} 20972 20973This generic package provides a random number generator suitable for generating 20974uniformly distributed values of a specified discrete subtype. 20975 20976@item @code{Ada.Numerics.Float_Random} 20977 20978This package provides a random number generator suitable for generating 20979uniformly distributed floating point values in the unit interval. 20980 20981@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 20982 20983This is a generic version of the package that provides the 20984implementation of standard elementary functions (such as log and 20985trigonometric functions) for an arbitrary complex type. 20986 20987The following predefined instantiations of this package are provided: 20988 20989 20990@itemize * 20991 20992@item 20993@code{Short_Float} 20994 20995@code{Ada.Numerics.Short_Complex_Elementary_Functions} 20996 20997@item 20998@code{Float} 20999 21000@code{Ada.Numerics.Complex_Elementary_Functions} 21001 21002@item 21003@code{Long_Float} 21004 21005@code{Ada.Numerics.Long_Complex_Elementary_Functions} 21006@end itemize 21007 21008@item @code{Ada.Numerics.Generic_Complex_Types} 21009 21010This is a generic package that allows the creation of complex types, 21011with associated complex arithmetic operations. 21012 21013The following predefined instantiations of this package exist 21014 21015 21016@itemize * 21017 21018@item 21019@code{Short_Float} 21020 21021@code{Ada.Numerics.Short_Complex_Complex_Types} 21022 21023@item 21024@code{Float} 21025 21026@code{Ada.Numerics.Complex_Complex_Types} 21027 21028@item 21029@code{Long_Float} 21030 21031@code{Ada.Numerics.Long_Complex_Complex_Types} 21032@end itemize 21033 21034@item @code{Ada.Numerics.Generic_Elementary_Functions} 21035 21036This is a generic package that provides the implementation of standard 21037elementary functions (such as log an trigonometric functions) for an 21038arbitrary float type. 21039 21040The following predefined instantiations of this package exist 21041 21042 21043@itemize * 21044 21045@item 21046@code{Short_Float} 21047 21048@code{Ada.Numerics.Short_Elementary_Functions} 21049 21050@item 21051@code{Float} 21052 21053@code{Ada.Numerics.Elementary_Functions} 21054 21055@item 21056@code{Long_Float} 21057 21058@code{Ada.Numerics.Long_Elementary_Functions} 21059@end itemize 21060 21061@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 21062 21063Generic operations on arrays of reals 21064 21065@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 21066 21067Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 21068 21069@item @code{Ada.Real_Time} @emph{(D.8)} 21070 21071This package provides facilities similar to those of @code{Calendar}, but 21072operating with a finer clock suitable for real time control. Note that 21073annex D requires that there be no backward clock jumps, and GNAT generally 21074guarantees this behavior, but of course if the external clock on which 21075the GNAT runtime depends is deliberately reset by some external event, 21076then such a backward jump may occur. 21077 21078@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 21079 21080Not implemented in GNAT. 21081 21082@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 21083 21084This package provides input-output facilities for sequential files, 21085which can contain a sequence of values of a single type, which can be 21086any Ada type, including indefinite (unconstrained) types. 21087 21088@item @code{Ada.Storage_IO} @emph{(A.9)} 21089 21090This package provides a facility for mapping arbitrary Ada types to and 21091from a storage buffer. It is primarily intended for the creation of new 21092IO packages. 21093 21094@item @code{Ada.Streams} @emph{(13.13.1)} 21095 21096This is a generic package that provides the basic support for the 21097concept of streams as used by the stream attributes (@code{Input}, 21098@code{Output}, @code{Read} and @code{Write}). 21099 21100@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 21101 21102This package is a specialization of the type @code{Streams} defined in 21103package @code{Streams} together with a set of operations providing 21104Stream_IO capability. The Stream_IO model permits both random and 21105sequential access to a file which can contain an arbitrary set of values 21106of one or more Ada types. 21107 21108@item @code{Ada.Strings} @emph{(A.4.1)} 21109 21110This package provides some basic constants used by the string handling 21111packages. 21112 21113@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 21114 21115This package provides facilities for handling variable length 21116strings. The bounded model requires a maximum length. It is thus 21117somewhat more limited than the unbounded model, but avoids the use of 21118dynamic allocation or finalization. 21119 21120@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 21121 21122Provides case-insensitive comparisons of bounded strings 21123 21124@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 21125 21126This package provides a generic hash function for bounded strings 21127 21128@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 21129 21130This package provides a generic hash function for bounded strings that 21131converts the string to be hashed to lower case. 21132 21133@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 21134 21135This package provides a comparison function for bounded strings that works 21136in a case insensitive manner by converting to lower case before the comparison. 21137 21138@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 21139 21140This package provides facilities for handling fixed length strings. 21141 21142@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 21143 21144This package provides an equality function for fixed strings that compares 21145the strings after converting both to lower case. 21146 21147@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 21148 21149This package provides a case insensitive hash function for fixed strings that 21150converts the string to lower case before computing the hash. 21151 21152@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 21153 21154This package provides a comparison function for fixed strings that works 21155in a case insensitive manner by converting to lower case before the comparison. 21156 21157@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 21158 21159This package provides a hash function for strings. 21160 21161@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 21162 21163This package provides a hash function for strings that is case insensitive. 21164The string is converted to lower case before computing the hash. 21165 21166@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 21167 21168This package provides a comparison function for\strings that works 21169in a case insensitive manner by converting to lower case before the comparison. 21170 21171@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 21172 21173This package provides facilities for handling character mappings and 21174arbitrarily defined subsets of characters. For instance it is useful in 21175defining specialized translation tables. 21176 21177@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 21178 21179This package provides a standard set of predefined mappings and 21180predefined character sets. For example, the standard upper to lower case 21181conversion table is found in this package. Note that upper to lower case 21182conversion is non-trivial if you want to take the entire set of 21183characters, including extended characters like E with an acute accent, 21184into account. You should use the mappings in this package (rather than 21185adding 32 yourself) to do case mappings. 21186 21187@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 21188 21189This package provides facilities for handling variable length 21190strings. The unbounded model allows arbitrary length strings, but 21191requires the use of dynamic allocation and finalization. 21192 21193@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 21194 21195Provides case-insensitive comparisons of unbounded strings 21196 21197@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 21198 21199This package provides a generic hash function for unbounded strings 21200 21201@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 21202 21203This package provides a generic hash function for unbounded strings that 21204converts the string to be hashed to lower case. 21205 21206@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 21207 21208This package provides a comparison function for unbounded strings that works 21209in a case insensitive manner by converting to lower case before the comparison. 21210 21211@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 21212 21213This package provides basic definitions for dealing with UTF-encoded strings. 21214 21215@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 21216 21217This package provides conversion functions for UTF-encoded strings. 21218@end table 21219 21220@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 21221 21222@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 21223 21224 21225@table @asis 21226 21227@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 21228 21229These packages provide facilities for handling UTF encodings for 21230Strings, Wide_Strings and Wide_Wide_Strings. 21231@end table 21232 21233@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 21234 21235@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 21236 21237@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 21238 21239 21240@table @asis 21241 21242@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 21243 21244These packages provide analogous capabilities to the corresponding 21245packages without @code{Wide_} in the name, but operate with the types 21246@code{Wide_String} and @code{Wide_Character} instead of @code{String} 21247and @code{Character}. Versions of all the child packages are available. 21248@end table 21249 21250@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 21251 21252@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 21253 21254@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 21255 21256 21257@table @asis 21258 21259@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 21260 21261These packages provide analogous capabilities to the corresponding 21262packages without @code{Wide_} in the name, but operate with the types 21263@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 21264of @code{String} and @code{Character}. 21265 21266@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 21267 21268This package provides facilities for synchronizing tasks at a low level 21269with barriers. 21270 21271@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 21272 21273This package provides some standard facilities for controlling task 21274communication in a synchronous manner. 21275 21276@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 21277 21278Not implemented in GNAT. 21279 21280@item @code{Ada.Tags} 21281 21282This package contains definitions for manipulation of the tags of tagged 21283values. 21284 21285@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 21286 21287This package provides a way of constructing tagged class-wide values given 21288only the tag value. 21289 21290@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 21291 21292This package provides the capability of associating arbitrary 21293task-specific data with separate tasks. 21294 21295@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 21296 21297This package provides capabilities for task identification. 21298 21299@item @code{Ada.Task_Termination} @emph{(C.7.3)} 21300 21301This package provides control over task termination. 21302 21303@item @code{Ada.Text_IO} 21304 21305This package provides basic text input-output capabilities for 21306character, string and numeric data. The subpackages of this 21307package are listed next. Note that although these are defined 21308as subpackages in the RM, they are actually transparently 21309implemented as child packages in GNAT, meaning that they 21310are only loaded if needed. 21311 21312@item @code{Ada.Text_IO.Decimal_IO} 21313 21314Provides input-output facilities for decimal fixed-point types 21315 21316@item @code{Ada.Text_IO.Enumeration_IO} 21317 21318Provides input-output facilities for enumeration types. 21319 21320@item @code{Ada.Text_IO.Fixed_IO} 21321 21322Provides input-output facilities for ordinary fixed-point types. 21323 21324@item @code{Ada.Text_IO.Float_IO} 21325 21326Provides input-output facilities for float types. The following 21327predefined instantiations of this generic package are available: 21328 21329 21330@itemize * 21331 21332@item 21333@code{Short_Float} 21334 21335@code{Short_Float_Text_IO} 21336 21337@item 21338@code{Float} 21339 21340@code{Float_Text_IO} 21341 21342@item 21343@code{Long_Float} 21344 21345@code{Long_Float_Text_IO} 21346@end itemize 21347 21348@item @code{Ada.Text_IO.Integer_IO} 21349 21350Provides input-output facilities for integer types. The following 21351predefined instantiations of this generic package are available: 21352 21353 21354@itemize * 21355 21356@item 21357@code{Short_Short_Integer} 21358 21359@code{Ada.Short_Short_Integer_Text_IO} 21360 21361@item 21362@code{Short_Integer} 21363 21364@code{Ada.Short_Integer_Text_IO} 21365 21366@item 21367@code{Integer} 21368 21369@code{Ada.Integer_Text_IO} 21370 21371@item 21372@code{Long_Integer} 21373 21374@code{Ada.Long_Integer_Text_IO} 21375 21376@item 21377@code{Long_Long_Integer} 21378 21379@code{Ada.Long_Long_Integer_Text_IO} 21380@end itemize 21381 21382@item @code{Ada.Text_IO.Modular_IO} 21383 21384Provides input-output facilities for modular (unsigned) types. 21385 21386@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 21387 21388Provides input-output facilities for bounded strings. 21389 21390@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 21391 21392This package provides basic text input-output capabilities for complex 21393data. 21394 21395@item @code{Ada.Text_IO.Editing (F.3.3)} 21396 21397This package contains routines for edited output, analogous to the use 21398of pictures in COBOL. The picture formats used by this package are a 21399close copy of the facility in COBOL. 21400 21401@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 21402 21403This package provides a facility that allows Text_IO files to be treated 21404as streams, so that the stream attributes can be used for writing 21405arbitrary data, including binary data, to Text_IO files. 21406 21407@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 21408 21409This package provides input-output facilities for unbounded strings. 21410 21411@item @code{Ada.Unchecked_Conversion (13.9)} 21412 21413This generic package allows arbitrary conversion from one type to 21414another of the same size, providing for breaking the type safety in 21415special circumstances. 21416 21417If the types have the same Size (more accurately the same Value_Size), 21418then the effect is simply to transfer the bits from the source to the 21419target type without any modification. This usage is well defined, and 21420for simple types whose representation is typically the same across 21421all implementations, gives a portable method of performing such 21422conversions. 21423 21424If the types do not have the same size, then the result is implementation 21425defined, and thus may be non-portable. The following describes how GNAT 21426handles such unchecked conversion cases. 21427 21428If the types are of different sizes, and are both discrete types, then 21429the effect is of a normal type conversion without any constraint checking. 21430In particular if the result type has a larger size, the result will be 21431zero or sign extended. If the result type has a smaller size, the result 21432will be truncated by ignoring high order bits. 21433 21434If the types are of different sizes, and are not both discrete types, 21435then the conversion works as though pointers were created to the source 21436and target, and the pointer value is converted. The effect is that bits 21437are copied from successive low order storage units and bits of the source 21438up to the length of the target type. 21439 21440A warning is issued if the lengths differ, since the effect in this 21441case is implementation dependent, and the above behavior may not match 21442that of some other compiler. 21443 21444A pointer to one type may be converted to a pointer to another type using 21445unchecked conversion. The only case in which the effect is undefined is 21446when one or both pointers are pointers to unconstrained array types. In 21447this case, the bounds information may get incorrectly transferred, and in 21448particular, GNAT uses double size pointers for such types, and it is 21449meaningless to convert between such pointer types. GNAT will issue a 21450warning if the alignment of the target designated type is more strict 21451than the alignment of the source designated type (since the result may 21452be unaligned in this case). 21453 21454A pointer other than a pointer to an unconstrained array type may be 21455converted to and from System.Address. Such usage is common in Ada 83 21456programs, but note that Ada.Address_To_Access_Conversions is the 21457preferred method of performing such conversions in Ada 95 and Ada 2005. 21458Neither 21459unchecked conversion nor Ada.Address_To_Access_Conversions should be 21460used in conjunction with pointers to unconstrained objects, since 21461the bounds information cannot be handled correctly in this case. 21462 21463@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 21464 21465This generic package allows explicit freeing of storage previously 21466allocated by use of an allocator. 21467 21468@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 21469 21470This package is similar to @code{Ada.Text_IO}, except that the external 21471file supports wide character representations, and the internal types are 21472@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21473and @code{String}. The corresponding set of nested packages and child 21474packages are defined. 21475 21476@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 21477 21478This package is similar to @code{Ada.Text_IO}, except that the external 21479file supports wide character representations, and the internal types are 21480@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21481and @code{String}. The corresponding set of nested packages and child 21482packages are defined. 21483@end table 21484 21485For packages in Interfaces and System, all the RM defined packages are 21486available in GNAT, see the Ada 2012 RM for full details. 21487 21488@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 21489@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{29e}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{29f} 21490@chapter The Implementation of Standard I/O 21491 21492 21493GNAT implements all the required input-output facilities described in 21494A.6 through A.14. These sections of the Ada Reference Manual describe the 21495required behavior of these packages from the Ada point of view, and if 21496you are writing a portable Ada program that does not need to know the 21497exact manner in which Ada maps to the outside world when it comes to 21498reading or writing external files, then you do not need to read this 21499chapter. As long as your files are all regular files (not pipes or 21500devices), and as long as you write and read the files only from Ada, the 21501description in the Ada Reference Manual is sufficient. 21502 21503However, if you want to do input-output to pipes or other devices, such 21504as the keyboard or screen, or if the files you are dealing with are 21505either generated by some other language, or to be read by some other 21506language, then you need to know more about the details of how the GNAT 21507implementation of these input-output facilities behaves. 21508 21509In this chapter we give a detailed description of exactly how GNAT 21510interfaces to the file system. As always, the sources of the system are 21511available to you for answering questions at an even more detailed level, 21512but for most purposes the information in this chapter will suffice. 21513 21514Another reason that you may need to know more about how input-output is 21515implemented arises when you have a program written in mixed languages 21516where, for example, files are shared between the C and Ada sections of 21517the same program. GNAT provides some additional facilities, in the form 21518of additional child library packages, that facilitate this sharing, and 21519these additional facilities are also described in this chapter. 21520 21521@menu 21522* Standard I/O Packages:: 21523* FORM Strings:: 21524* Direct_IO:: 21525* Sequential_IO:: 21526* Text_IO:: 21527* Wide_Text_IO:: 21528* Wide_Wide_Text_IO:: 21529* Stream_IO:: 21530* Text Translation:: 21531* Shared Files:: 21532* Filenames encoding:: 21533* File content encoding:: 21534* Open Modes:: 21535* Operations on C Streams:: 21536* Interfacing to C Streams:: 21537 21538@end menu 21539 21540@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 21541@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a0}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a1} 21542@section Standard I/O Packages 21543 21544 21545The Standard I/O packages described in Annex A for 21546 21547 21548@itemize * 21549 21550@item 21551Ada.Text_IO 21552 21553@item 21554Ada.Text_IO.Complex_IO 21555 21556@item 21557Ada.Text_IO.Text_Streams 21558 21559@item 21560Ada.Wide_Text_IO 21561 21562@item 21563Ada.Wide_Text_IO.Complex_IO 21564 21565@item 21566Ada.Wide_Text_IO.Text_Streams 21567 21568@item 21569Ada.Wide_Wide_Text_IO 21570 21571@item 21572Ada.Wide_Wide_Text_IO.Complex_IO 21573 21574@item 21575Ada.Wide_Wide_Text_IO.Text_Streams 21576 21577@item 21578Ada.Stream_IO 21579 21580@item 21581Ada.Sequential_IO 21582 21583@item 21584Ada.Direct_IO 21585@end itemize 21586 21587are implemented using the C 21588library streams facility; where 21589 21590 21591@itemize * 21592 21593@item 21594All files are opened using @code{fopen}. 21595 21596@item 21597All input/output operations use @code{fread}/@cite{fwrite}. 21598@end itemize 21599 21600There is no internal buffering of any kind at the Ada library level. The only 21601buffering is that provided at the system level in the implementation of the 21602library routines that support streams. This facilitates shared use of these 21603streams by mixed language programs. Note though that system level buffering is 21604explicitly enabled at elaboration of the standard I/O packages and that can 21605have an impact on mixed language programs, in particular those using I/O before 21606calling the Ada elaboration routine (e.g., adainit). It is recommended to call 21607the Ada elaboration routine before performing any I/O or when impractical, 21608flush the common I/O streams and in particular Standard_Output before 21609elaborating the Ada code. 21610 21611@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 21612@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a3} 21613@section FORM Strings 21614 21615 21616The format of a FORM string in GNAT is: 21617 21618@example 21619"keyword=value,keyword=value,...,keyword=value" 21620@end example 21621 21622where letters may be in upper or lower case, and there are no spaces 21623between values. The order of the entries is not important. Currently 21624the following keywords defined. 21625 21626@example 21627TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 21628SHARED=[YES|NO] 21629WCEM=[n|h|u|s|e|8|b] 21630ENCODING=[UTF8|8BITS] 21631@end example 21632 21633The use of these parameters is described later in this section. If an 21634unrecognized keyword appears in a form string, it is silently ignored 21635and not considered invalid. 21636 21637@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 21638@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a4}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a5} 21639@section Direct_IO 21640 21641 21642Direct_IO can only be instantiated for definite types. This is a 21643restriction of the Ada language, which means that the records are fixed 21644length (the length being determined by @code{type'Size}, rounded 21645up to the next storage unit boundary if necessary). 21646 21647The records of a Direct_IO file are simply written to the file in index 21648sequence, with the first record starting at offset zero, and subsequent 21649records following. There is no control information of any kind. For 21650example, if 32-bit integers are being written, each record takes 216514-bytes, so the record at index @code{K} starts at offset 21652(@code{K}-1)*4. 21653 21654There is no limit on the size of Direct_IO files, they are expanded as 21655necessary to accommodate whatever records are written to the file. 21656 21657@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 21658@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2a6}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a7} 21659@section Sequential_IO 21660 21661 21662Sequential_IO may be instantiated with either a definite (constrained) 21663or indefinite (unconstrained) type. 21664 21665For the definite type case, the elements written to the file are simply 21666the memory images of the data values with no control information of any 21667kind. The resulting file should be read using the same type, no validity 21668checking is performed on input. 21669 21670For the indefinite type case, the elements written consist of two 21671parts. First is the size of the data item, written as the memory image 21672of a @code{Interfaces.C.size_t} value, followed by the memory image of 21673the data value. The resulting file can only be read using the same 21674(unconstrained) type. Normal assignment checks are performed on these 21675read operations, and if these checks fail, @code{Data_Error} is 21676raised. In particular, in the array case, the lengths must match, and in 21677the variant record case, if the variable for a particular read operation 21678is constrained, the discriminants must match. 21679 21680Note that it is not possible to use Sequential_IO to write variable 21681length array items, and then read the data back into different length 21682arrays. For example, the following will raise @code{Data_Error}: 21683 21684@example 21685package IO is new Sequential_IO (String); 21686F : IO.File_Type; 21687S : String (1..4); 21688... 21689IO.Create (F) 21690IO.Write (F, "hello!") 21691IO.Reset (F, Mode=>In_File); 21692IO.Read (F, S); 21693Put_Line (S); 21694@end example 21695 21696On some Ada implementations, this will print @code{hell}, but the program is 21697clearly incorrect, since there is only one element in the file, and that 21698element is the string @code{hello!}. 21699 21700In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 21701using Stream_IO, and this is the preferred mechanism. In particular, the 21702above program fragment rewritten to use Stream_IO will work correctly. 21703 21704@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 21705@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2a8}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2a9} 21706@section Text_IO 21707 21708 21709Text_IO files consist of a stream of characters containing the following 21710special control characters: 21711 21712@example 21713LF (line feed, 16#0A#) Line Mark 21714FF (form feed, 16#0C#) Page Mark 21715@end example 21716 21717A canonical Text_IO file is defined as one in which the following 21718conditions are met: 21719 21720 21721@itemize * 21722 21723@item 21724The character @code{LF} is used only as a line mark, i.e., to mark the end 21725of the line. 21726 21727@item 21728The character @code{FF} is used only as a page mark, i.e., to mark the 21729end of a page and consequently can appear only immediately following a 21730@code{LF} (line mark) character. 21731 21732@item 21733The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} 21734(line mark, page mark). In the former case, the page mark is implicitly 21735assumed to be present. 21736@end itemize 21737 21738A file written using Text_IO will be in canonical form provided that no 21739explicit @code{LF} or @code{FF} characters are written using @code{Put} 21740or @code{Put_Line}. There will be no @code{FF} character at the end of 21741the file unless an explicit @code{New_Page} operation was performed 21742before closing the file. 21743 21744A canonical Text_IO file that is a regular file (i.e., not a device or a 21745pipe) can be read using any of the routines in Text_IO. The 21746semantics in this case will be exactly as defined in the Ada Reference 21747Manual, and all the routines in Text_IO are fully implemented. 21748 21749A text file that does not meet the requirements for a canonical Text_IO 21750file has one of the following: 21751 21752 21753@itemize * 21754 21755@item 21756The file contains @code{FF} characters not immediately following a 21757@code{LF} character. 21758 21759@item 21760The file contains @code{LF} or @code{FF} characters written by 21761@code{Put} or @code{Put_Line}, which are not logically considered to be 21762line marks or page marks. 21763 21764@item 21765The file ends in a character other than @code{LF} or @code{FF}, 21766i.e., there is no explicit line mark or page mark at the end of the file. 21767@end itemize 21768 21769Text_IO can be used to read such non-standard text files but subprograms 21770to do with line or page numbers do not have defined meanings. In 21771particular, a @code{FF} character that does not follow a @code{LF} 21772character may or may not be treated as a page mark from the point of 21773view of page and line numbering. Every @code{LF} character is considered 21774to end a line, and there is an implied @code{LF} character at the end of 21775the file. 21776 21777@menu 21778* Stream Pointer Positioning:: 21779* Reading and Writing Non-Regular Files:: 21780* Get_Immediate:: 21781* Treating Text_IO Files as Streams:: 21782* Text_IO Extensions:: 21783* Text_IO Facilities for Unbounded Strings:: 21784 21785@end menu 21786 21787@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21788@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2aa}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ab} 21789@subsection Stream Pointer Positioning 21790 21791 21792@code{Ada.Text_IO} has a definition of current position for a file that 21793is being read. No internal buffering occurs in Text_IO, and usually the 21794physical position in the stream used to implement the file corresponds 21795to this logical position defined by Text_IO. There are two exceptions: 21796 21797 21798@itemize * 21799 21800@item 21801After a call to @code{End_Of_Page} that returns @code{True}, the stream 21802is positioned past the @code{LF} (line mark) that precedes the page 21803mark. Text_IO maintains an internal flag so that subsequent read 21804operations properly handle the logical position which is unchanged by 21805the @code{End_Of_Page} call. 21806 21807@item 21808After a call to @code{End_Of_File} that returns @code{True}, if the 21809Text_IO file was positioned before the line mark at the end of file 21810before the call, then the logical position is unchanged, but the stream 21811is physically positioned right at the end of file (past the line mark, 21812and past a possible page mark following the line mark. Again Text_IO 21813maintains internal flags so that subsequent read operations properly 21814handle the logical position. 21815@end itemize 21816 21817These discrepancies have no effect on the observable behavior of 21818Text_IO, but if a single Ada stream is shared between a C program and 21819Ada program, or shared (using @code{shared=yes} in the form string) 21820between two Ada files, then the difference may be observable in some 21821situations. 21822 21823@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21824@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2ac}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2ad} 21825@subsection Reading and Writing Non-Regular Files 21826 21827 21828A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21829can be used for reading and writing. Writing is not affected and the 21830sequence of characters output is identical to the normal file case, but 21831for reading, the behavior of Text_IO is modified to avoid undesirable 21832look-ahead as follows: 21833 21834An input file that is not a regular file is considered to have no page 21835marks. Any @code{Ascii.FF} characters (the character normally used for a 21836page mark) appearing in the file are considered to be data 21837characters. In particular: 21838 21839 21840@itemize * 21841 21842@item 21843@code{Get_Line} and @code{Skip_Line} do not test for a page mark 21844following a line mark. If a page mark appears, it will be treated as a 21845data character. 21846 21847@item 21848This avoids the need to wait for an extra character to be typed or 21849entered from the pipe to complete one of these operations. 21850 21851@item 21852@code{End_Of_Page} always returns @code{False} 21853 21854@item 21855@code{End_Of_File} will return @code{False} if there is a page mark at 21856the end of the file. 21857@end itemize 21858 21859Output to non-regular files is the same as for regular files. Page marks 21860may be written to non-regular files using @code{New_Page}, but as noted 21861above they will not be treated as page marks on input if the output is 21862piped to another Ada program. 21863 21864Another important discrepancy when reading non-regular files is that the end 21865of file indication is not 'sticky'. If an end of file is entered, e.g., by 21866pressing the @code{EOT} key, 21867then end of file 21868is signaled once (i.e., the test @code{End_Of_File} 21869will yield @code{True}, or a read will 21870raise @code{End_Error}), but then reading can resume 21871to read data past that end of 21872file indication, until another end of file indication is entered. 21873 21874@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21875@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2af} 21876@subsection Get_Immediate 21877 21878 21879@geindex Get_Immediate 21880 21881Get_Immediate returns the next character (including control characters) 21882from the input file. In particular, Get_Immediate will return LF or FF 21883characters used as line marks or page marks. Such operations leave the 21884file positioned past the control character, and it is thus not treated 21885as having its normal function. This means that page, line and column 21886counts after this kind of Get_Immediate call are set as though the mark 21887did not occur. In the case where a Get_Immediate leaves the file 21888positioned between the line mark and page mark (which is not normally 21889possible), it is undefined whether the FF character will be treated as a 21890page mark. 21891 21892@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21893@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b0}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b1} 21894@subsection Treating Text_IO Files as Streams 21895 21896 21897@geindex Stream files 21898 21899The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated 21900as a stream. Data written to a @code{Text_IO} file in this stream mode is 21901binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 2190216#0C# (@code{FF}), the resulting file may have non-standard 21903format. Similarly if read operations are used to read from a Text_IO 21904file treated as a stream, then @code{LF} and @code{FF} characters may be 21905skipped and the effect is similar to that described above for 21906@code{Get_Immediate}. 21907 21908@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 21909@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b2}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b3} 21910@subsection Text_IO Extensions 21911 21912 21913@geindex Text_IO extensions 21914 21915A package GNAT.IO_Aux in the GNAT library provides some useful extensions 21916to the standard @code{Text_IO} package: 21917 21918 21919@itemize * 21920 21921@item 21922function File_Exists (Name : String) return Boolean; 21923Determines if a file of the given name exists. 21924 21925@item 21926function Get_Line return String; 21927Reads a string from the standard input file. The value returned is exactly 21928the length of the line that was read. 21929 21930@item 21931function Get_Line (File : Ada.Text_IO.File_Type) return String; 21932Similar, except that the parameter File specifies the file from which 21933the string is to be read. 21934@end itemize 21935 21936@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 21937@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b4}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b5} 21938@subsection Text_IO Facilities for Unbounded Strings 21939 21940 21941@geindex Text_IO for unbounded strings 21942 21943@geindex Unbounded_String 21944@geindex Text_IO operations 21945 21946The package @code{Ada.Strings.Unbounded.Text_IO} 21947in library files @code{a-suteio.ads/adb} contains some GNAT-specific 21948subprograms useful for Text_IO operations on unbounded strings: 21949 21950 21951@itemize * 21952 21953@item 21954function Get_Line (File : File_Type) return Unbounded_String; 21955Reads a line from the specified file 21956and returns the result as an unbounded string. 21957 21958@item 21959procedure Put (File : File_Type; U : Unbounded_String); 21960Writes the value of the given unbounded string to the specified file 21961Similar to the effect of 21962@code{Put (To_String (U))} except that an extra copy is avoided. 21963 21964@item 21965procedure Put_Line (File : File_Type; U : Unbounded_String); 21966Writes the value of the given unbounded string to the specified file, 21967followed by a @code{New_Line}. 21968Similar to the effect of @code{Put_Line (To_String (U))} except 21969that an extra copy is avoided. 21970@end itemize 21971 21972In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 21973and is optional. If the parameter is omitted, then the standard input or 21974output file is referenced as appropriate. 21975 21976The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 21977files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 21978@code{Wide_Text_IO} functionality for unbounded wide strings. 21979 21980The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 21981files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 21982@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 21983 21984@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 21985@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2b6}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b7} 21986@section Wide_Text_IO 21987 21988 21989@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 21990both input and output files may contain special sequences that represent 21991wide character values. The encoding scheme for a given file may be 21992specified using a FORM parameter: 21993 21994@example 21995WCEM=`x` 21996@end example 21997 21998as part of the FORM string (WCEM = wide character encoding method), 21999where @code{x} is one of the following characters 22000 22001 22002@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 22003@headitem 22004 22005Character 22006 22007@tab 22008 22009Encoding 22010 22011@item 22012 22013@emph{h} 22014 22015@tab 22016 22017Hex ESC encoding 22018 22019@item 22020 22021@emph{u} 22022 22023@tab 22024 22025Upper half encoding 22026 22027@item 22028 22029@emph{s} 22030 22031@tab 22032 22033Shift-JIS encoding 22034 22035@item 22036 22037@emph{e} 22038 22039@tab 22040 22041EUC Encoding 22042 22043@item 22044 22045@emph{8} 22046 22047@tab 22048 22049UTF-8 encoding 22050 22051@item 22052 22053@emph{b} 22054 22055@tab 22056 22057Brackets encoding 22058 22059@end multitable 22060 22061 22062The encoding methods match those that 22063can be used in a source 22064program, but there is no requirement that the encoding method used for 22065the source program be the same as the encoding method used for files, 22066and different files may use different encoding methods. 22067 22068The default encoding method for the standard files, and for opened files 22069for which no WCEM parameter is given in the FORM string matches the 22070wide character encoding specified for the main program (the default 22071being brackets encoding if no coding method was specified with -gnatW). 22072 22073 22074@table @asis 22075 22076@item @emph{Hex Coding} 22077 22078In this encoding, a wide character is represented by a five character 22079sequence: 22080@end table 22081 22082@example 22083ESC a b c d 22084@end example 22085 22086 22087@quotation 22088 22089where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 22090characters (using upper case letters) of the wide character code. For 22091example, ESC A345 is used to represent the wide character with code 2209216#A345#. This scheme is compatible with use of the full 22093@code{Wide_Character} set. 22094@end quotation 22095 22096 22097@table @asis 22098 22099@item @emph{Upper Half Coding} 22100 22101The wide character with encoding 16#abcd#, where the upper bit is on 22102(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2210316#cd#. The second byte may never be a format control character, but is 22104not required to be in the upper half. This method can be also used for 22105shift-JIS or EUC where the internal coding matches the external coding. 22106 22107@item @emph{Shift JIS Coding} 22108 22109A wide character is represented by a two character sequence 16#ab# and 2211016#cd#, with the restrictions described for upper half encoding as 22111described above. The internal character code is the corresponding JIS 22112character according to the standard algorithm for Shift-JIS 22113conversion. Only characters defined in the JIS code set table can be 22114used with this encoding method. 22115 22116@item @emph{EUC Coding} 22117 22118A wide character is represented by a two character sequence 16#ab# and 2211916#cd#, with both characters being in the upper half. The internal 22120character code is the corresponding JIS character according to the EUC 22121encoding algorithm. Only characters defined in the JIS code set table 22122can be used with this encoding method. 22123 22124@item @emph{UTF-8 Coding} 22125 22126A wide character is represented using 22127UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2212810646-1/Am.2. Depending on the character value, the representation 22129is a one, two, or three byte sequence: 22130@end table 22131 22132@example 2213316#0000#-16#007f#: 2#0xxxxxxx# 2213416#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2213516#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 22136@end example 22137 22138 22139@quotation 22140 22141where the @code{xxx} bits correspond to the left-padded bits of the 2214216-bit character value. Note that all lower half ASCII characters 22143are represented as ASCII bytes and all upper half characters and 22144other wide characters are represented as sequences of upper-half 22145(The full UTF-8 scheme allows for encoding 31-bit characters as 221466-byte sequences, but in this implementation, all UTF-8 sequences 22147of four or more bytes length will raise a Constraint_Error, as 22148will all invalid UTF-8 sequences.) 22149@end quotation 22150 22151 22152@table @asis 22153 22154@item @emph{Brackets Coding} 22155 22156In this encoding, a wide character is represented by the following eight 22157character sequence: 22158@end table 22159 22160@example 22161[ " a b c d " ] 22162@end example 22163 22164 22165@quotation 22166 22167where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 22168characters (using uppercase letters) of the wide character code. For 22169example, @code{["A345"]} is used to represent the wide character with code 22170@code{16#A345#}. 22171This scheme is compatible with use of the full Wide_Character set. 22172On input, brackets coding can also be used for upper half characters, 22173e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22174is only used for wide characters with a code greater than @code{16#FF#}. 22175 22176Note that brackets coding is not normally used in the context of 22177Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 22178a portable way of encoding source files. In the context of Wide_Text_IO 22179or Wide_Wide_Text_IO, it can only be used if the file does not contain 22180any instance of the left bracket character other than to encode wide 22181character values using the brackets encoding method. In practice it is 22182expected that some standard wide character encoding method such 22183as UTF-8 will be used for text input output. 22184 22185If brackets notation is used, then any occurrence of a left bracket 22186in the input file which is not the start of a valid wide character 22187sequence will cause Constraint_Error to be raised. It is possible to 22188encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 22189input will interpret this as a left bracket. 22190 22191However, when a left bracket is output, it will be output as a left bracket 22192and not as ["5B"]. We make this decision because for normal use of 22193Wide_Text_IO for outputting messages, it is unpleasant to clobber left 22194brackets. For example, if we write: 22195 22196@example 22197Put_Line ("Start of output [first run]"); 22198@end example 22199 22200we really do not want to have the left bracket in this message clobbered so 22201that the output reads: 22202@end quotation 22203 22204@example 22205Start of output ["5B"]first run] 22206@end example 22207 22208 22209@quotation 22210 22211In practice brackets encoding is reasonably useful for normal Put_Line use 22212since we won't get confused between left brackets and wide character 22213sequences in the output. But for input, or when files are written out 22214and read back in, it really makes better sense to use one of the standard 22215encoding methods such as UTF-8. 22216@end quotation 22217 22218For the coding schemes other than UTF-8, Hex, or Brackets encoding, 22219not all wide character 22220values can be represented. An attempt to output a character that cannot 22221be represented using the encoding scheme for the file causes 22222Constraint_Error to be raised. An invalid wide character sequence on 22223input also causes Constraint_Error to be raised. 22224 22225@menu 22226* Stream Pointer Positioning: Stream Pointer Positioning<2>. 22227* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 22228 22229@end menu 22230 22231@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 22232@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2b8}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2b9} 22233@subsection Stream Pointer Positioning 22234 22235 22236@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22237of stream pointer positioning (@ref{2a9,,Text_IO}). There is one additional 22238case: 22239 22240If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 22241normal lower ASCII set (i.e., a character in the range: 22242 22243@example 22244Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 22245@end example 22246 22247then although the logical position of the file pointer is unchanged by 22248the @code{Look_Ahead} call, the stream is physically positioned past the 22249wide character sequence. Again this is to avoid the need for buffering 22250or backup, and all @code{Wide_Text_IO} routines check the internal 22251indication that this situation has occurred so that this is not visible 22252to a normal program using @code{Wide_Text_IO}. However, this discrepancy 22253can be observed if the wide text file shares a stream with another file. 22254 22255@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 22256@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2ba}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bb} 22257@subsection Reading and Writing Non-Regular Files 22258 22259 22260As in the case of Text_IO, when a non-regular file is read, it is 22261assumed that the file contains no page marks (any form characters are 22262treated as data characters), and @code{End_Of_Page} always returns 22263@code{False}. Similarly, the end of file indication is not sticky, so 22264it is possible to read beyond an end of file. 22265 22266@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 22267@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bc}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2bd} 22268@section Wide_Wide_Text_IO 22269 22270 22271@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 22272both input and output files may contain special sequences that represent 22273wide wide character values. The encoding scheme for a given file may be 22274specified using a FORM parameter: 22275 22276@example 22277WCEM=`x` 22278@end example 22279 22280as part of the FORM string (WCEM = wide character encoding method), 22281where @code{x} is one of the following characters 22282 22283 22284@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 22285@headitem 22286 22287Character 22288 22289@tab 22290 22291Encoding 22292 22293@item 22294 22295@emph{h} 22296 22297@tab 22298 22299Hex ESC encoding 22300 22301@item 22302 22303@emph{u} 22304 22305@tab 22306 22307Upper half encoding 22308 22309@item 22310 22311@emph{s} 22312 22313@tab 22314 22315Shift-JIS encoding 22316 22317@item 22318 22319@emph{e} 22320 22321@tab 22322 22323EUC Encoding 22324 22325@item 22326 22327@emph{8} 22328 22329@tab 22330 22331UTF-8 encoding 22332 22333@item 22334 22335@emph{b} 22336 22337@tab 22338 22339Brackets encoding 22340 22341@end multitable 22342 22343 22344The encoding methods match those that 22345can be used in a source 22346program, but there is no requirement that the encoding method used for 22347the source program be the same as the encoding method used for files, 22348and different files may use different encoding methods. 22349 22350The default encoding method for the standard files, and for opened files 22351for which no WCEM parameter is given in the FORM string matches the 22352wide character encoding specified for the main program (the default 22353being brackets encoding if no coding method was specified with -gnatW). 22354 22355 22356@table @asis 22357 22358@item @emph{UTF-8 Coding} 22359 22360A wide character is represented using 22361UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2236210646-1/Am.2. Depending on the character value, the representation 22363is a one, two, three, or four byte sequence: 22364@end table 22365 22366@example 2236716#000000#-16#00007f#: 2#0xxxxxxx# 2236816#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2236916#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2237016#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 22371@end example 22372 22373 22374@quotation 22375 22376where the @code{xxx} bits correspond to the left-padded bits of the 2237721-bit character value. Note that all lower half ASCII characters 22378are represented as ASCII bytes and all upper half characters and 22379other wide characters are represented as sequences of upper-half 22380characters. 22381@end quotation 22382 22383 22384@table @asis 22385 22386@item @emph{Brackets Coding} 22387 22388In this encoding, a wide wide character is represented by the following eight 22389character sequence if is in wide character range 22390@end table 22391 22392@example 22393[ " a b c d " ] 22394@end example 22395 22396 22397@quotation 22398 22399and by the following ten character sequence if not 22400@end quotation 22401 22402@example 22403[ " a b c d e f " ] 22404@end example 22405 22406 22407@quotation 22408 22409where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 22410are the four or six hexadecimal 22411characters (using uppercase letters) of the wide wide character code. For 22412example, @code{["01A345"]} is used to represent the wide wide character 22413with code @code{16#01A345#}. 22414 22415This scheme is compatible with use of the full Wide_Wide_Character set. 22416On input, brackets coding can also be used for upper half characters, 22417e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22418is only used for wide characters with a code greater than @code{16#FF#}. 22419@end quotation 22420 22421If is also possible to use the other Wide_Character encoding methods, 22422such as Shift-JIS, but the other schemes cannot support the full range 22423of wide wide characters. 22424An attempt to output a character that cannot 22425be represented using the encoding scheme for the file causes 22426Constraint_Error to be raised. An invalid wide character sequence on 22427input also causes Constraint_Error to be raised. 22428 22429@menu 22430* Stream Pointer Positioning: Stream Pointer Positioning<3>. 22431* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 22432 22433@end menu 22434 22435@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 22436@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2be}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2bf} 22437@subsection Stream Pointer Positioning 22438 22439 22440@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22441of stream pointer positioning (@ref{2a9,,Text_IO}). There is one additional 22442case: 22443 22444If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 22445normal lower ASCII set (i.e., a character in the range: 22446 22447@example 22448Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 22449@end example 22450 22451then although the logical position of the file pointer is unchanged by 22452the @code{Look_Ahead} call, the stream is physically positioned past the 22453wide character sequence. Again this is to avoid the need for buffering 22454or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 22455indication that this situation has occurred so that this is not visible 22456to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 22457can be observed if the wide text file shares a stream with another file. 22458 22459@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 22460@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c0}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c1} 22461@subsection Reading and Writing Non-Regular Files 22462 22463 22464As in the case of Text_IO, when a non-regular file is read, it is 22465assumed that the file contains no page marks (any form characters are 22466treated as data characters), and @code{End_Of_Page} always returns 22467@code{False}. Similarly, the end of file indication is not sticky, so 22468it is possible to read beyond an end of file. 22469 22470@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 22471@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c2}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c3} 22472@section Stream_IO 22473 22474 22475A stream file is a sequence of bytes, where individual elements are 22476written to the file as described in the Ada Reference Manual. The type 22477@code{Stream_Element} is simply a byte. There are two ways to read or 22478write a stream file. 22479 22480 22481@itemize * 22482 22483@item 22484The operations @code{Read} and @code{Write} directly read or write a 22485sequence of stream elements with no control information. 22486 22487@item 22488The stream attributes applied to a stream file transfer data in the 22489manner described for stream attributes. 22490@end itemize 22491 22492@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 22493@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c4}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c5} 22494@section Text Translation 22495 22496 22497@code{Text_Translation=xxx} may be used as the Form parameter 22498passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 22499has no effect on Unix systems. Possible values are: 22500 22501 22502@itemize * 22503 22504@item 22505@code{Yes} or @code{Text} is the default, which means to 22506translate LF to/from CR/LF on Windows systems. 22507 22508@code{No} disables this translation; i.e. it 22509uses binary mode. For output files, @code{Text_Translation=No} 22510may be used to create Unix-style files on 22511Windows. 22512 22513@item 22514@code{wtext} translation enabled in Unicode mode. 22515(corresponds to _O_WTEXT). 22516 22517@item 22518@code{u8text} translation enabled in Unicode UTF-8 mode. 22519(corresponds to O_U8TEXT). 22520 22521@item 22522@code{u16text} translation enabled in Unicode UTF-16 22523mode. (corresponds to_O_U16TEXT). 22524@end itemize 22525 22526@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 22527@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c6}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2c7} 22528@section Shared Files 22529 22530 22531Section A.14 of the Ada Reference Manual allows implementations to 22532provide a wide variety of behavior if an attempt is made to access the 22533same external file with two or more internal files. 22534 22535To provide a full range of functionality, while at the same time 22536minimizing the problems of portability caused by this implementation 22537dependence, GNAT handles file sharing as follows: 22538 22539 22540@itemize * 22541 22542@item 22543In the absence of a @code{shared=xxx} form parameter, an attempt 22544to open two or more files with the same full name is considered an error 22545and is not supported. The exception @code{Use_Error} will be 22546raised. Note that a file that is not explicitly closed by the program 22547remains open until the program terminates. 22548 22549@item 22550If the form parameter @code{shared=no} appears in the form string, the 22551file can be opened or created with its own separate stream identifier, 22552regardless of whether other files sharing the same external file are 22553opened. The exact effect depends on how the C stream routines handle 22554multiple accesses to the same external files using separate streams. 22555 22556@item 22557If the form parameter @code{shared=yes} appears in the form string for 22558each of two or more files opened using the same full name, the same 22559stream is shared between these files, and the semantics are as described 22560in Ada Reference Manual, Section A.14. 22561@end itemize 22562 22563When a program that opens multiple files with the same name is ported 22564from another Ada compiler to GNAT, the effect will be that 22565@code{Use_Error} is raised. 22566 22567The documentation of the original compiler and the documentation of the 22568program should then be examined to determine if file sharing was 22569expected, and @code{shared=xxx} parameters added to @code{Open} 22570and @code{Create} calls as required. 22571 22572When a program is ported from GNAT to some other Ada compiler, no 22573special attention is required unless the @code{shared=xxx} form 22574parameter is used in the program. In this case, you must examine the 22575documentation of the new compiler to see if it supports the required 22576file sharing semantics, and form strings modified appropriately. Of 22577course it may be the case that the program cannot be ported if the 22578target compiler does not support the required functionality. The best 22579approach in writing portable code is to avoid file sharing (and hence 22580the use of the @code{shared=xxx} parameter in the form string) 22581completely. 22582 22583One common use of file sharing in Ada 83 is the use of instantiations of 22584Sequential_IO on the same file with different types, to achieve 22585heterogeneous input-output. Although this approach will work in GNAT if 22586@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 22587for this purpose (using the stream attributes) 22588 22589@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 22590@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2c8}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2c9} 22591@section Filenames encoding 22592 22593 22594An encoding form parameter can be used to specify the filename 22595encoding @code{encoding=xxx}. 22596 22597 22598@itemize * 22599 22600@item 22601If the form parameter @code{encoding=utf8} appears in the form string, the 22602filename must be encoded in UTF-8. 22603 22604@item 22605If the form parameter @code{encoding=8bits} appears in the form 22606string, the filename must be a standard 8bits string. 22607@end itemize 22608 22609In the absence of a @code{encoding=xxx} form parameter, the 22610encoding is controlled by the @code{GNAT_CODE_PAGE} environment 22611variable. And if not set @code{utf8} is assumed. 22612 22613 22614@table @asis 22615 22616@item @emph{CP_ACP} 22617 22618The current system Windows ANSI code page. 22619 22620@item @emph{CP_UTF8} 22621 22622UTF-8 encoding 22623@end table 22624 22625This encoding form parameter is only supported on the Windows 22626platform. On the other Operating Systems the run-time is supporting 22627UTF-8 natively. 22628 22629@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 22630@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2ca}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2cb} 22631@section File content encoding 22632 22633 22634For text files it is possible to specify the encoding to use. This is 22635controlled by the by the @code{GNAT_CCS_ENCODING} environment 22636variable. And if not set @code{TEXT} is assumed. 22637 22638The possible values are those supported on Windows: 22639 22640 22641@table @asis 22642 22643@item @emph{TEXT} 22644 22645Translated text mode 22646 22647@item @emph{WTEXT} 22648 22649Translated unicode encoding 22650 22651@item @emph{U16TEXT} 22652 22653Unicode 16-bit encoding 22654 22655@item @emph{U8TEXT} 22656 22657Unicode 8-bit encoding 22658@end table 22659 22660This encoding is only supported on the Windows platform. 22661 22662@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 22663@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2cc}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cd} 22664@section Open Modes 22665 22666 22667@code{Open} and @code{Create} calls result in a call to @code{fopen} 22668using the mode shown in the following table: 22669 22670 22671@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 22672@headitem 22673 22674@code{Open} and @code{Create} Call Modes 22675 22676@tab 22677 22678@tab 22679 22680@item 22681 22682@tab 22683 22684@strong{OPEN} 22685 22686@tab 22687 22688@strong{CREATE} 22689 22690@item 22691 22692Append_File 22693 22694@tab 22695 22696"r+" 22697 22698@tab 22699 22700"w+" 22701 22702@item 22703 22704In_File 22705 22706@tab 22707 22708"r" 22709 22710@tab 22711 22712"w+" 22713 22714@item 22715 22716Out_File (Direct_IO) 22717 22718@tab 22719 22720"r+" 22721 22722@tab 22723 22724"w" 22725 22726@item 22727 22728Out_File (all other cases) 22729 22730@tab 22731 22732"w" 22733 22734@tab 22735 22736"w" 22737 22738@item 22739 22740Inout_File 22741 22742@tab 22743 22744"r+" 22745 22746@tab 22747 22748"w+" 22749 22750@end multitable 22751 22752 22753If text file translation is required, then either @code{b} or @code{t} 22754is added to the mode, depending on the setting of Text. Text file 22755translation refers to the mapping of CR/LF sequences in an external file 22756to LF characters internally. This mapping only occurs in DOS and 22757DOS-like systems, and is not relevant to other systems. 22758 22759A special case occurs with Stream_IO. As shown in the above table, the 22760file is initially opened in @code{r} or @code{w} mode for the 22761@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 22762subsequently requires switching from reading to writing or vice-versa, 22763then the file is reopened in @code{r+} mode to permit the required operation. 22764 22765@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22766@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2ce}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2cf} 22767@section Operations on C Streams 22768 22769 22770The package @code{Interfaces.C_Streams} provides an Ada program with direct 22771access to the C library functions for operations on C streams: 22772 22773@example 22774package Interfaces.C_Streams is 22775 -- Note: the reason we do not use the types that are in 22776 -- Interfaces.C is that we want to avoid dragging in the 22777 -- code in this unit if possible. 22778 subtype chars is System.Address; 22779 -- Pointer to null-terminated array of characters 22780 subtype FILEs is System.Address; 22781 -- Corresponds to the C type FILE* 22782 subtype voids is System.Address; 22783 -- Corresponds to the C type void* 22784 subtype int is Integer; 22785 subtype long is Long_Integer; 22786 -- Note: the above types are subtypes deliberately, and it 22787 -- is part of this spec that the above correspondences are 22788 -- guaranteed. This means that it is legitimate to, for 22789 -- example, use Integer instead of int. We provide these 22790 -- synonyms for clarity, but in some cases it may be 22791 -- convenient to use the underlying types (for example to 22792 -- avoid an unnecessary dependency of a spec on the spec 22793 -- of this unit). 22794 type size_t is mod 2 ** Standard'Address_Size; 22795 NULL_Stream : constant FILEs; 22796 -- Value returned (NULL in C) to indicate an 22797 -- fdopen/fopen/tmpfile error 22798 ---------------------------------- 22799 -- Constants Defined in stdio.h -- 22800 ---------------------------------- 22801 EOF : constant int; 22802 -- Used by a number of routines to indicate error or 22803 -- end of file 22804 IOFBF : constant int; 22805 IOLBF : constant int; 22806 IONBF : constant int; 22807 -- Used to indicate buffering mode for setvbuf call 22808 SEEK_CUR : constant int; 22809 SEEK_END : constant int; 22810 SEEK_SET : constant int; 22811 -- Used to indicate origin for fseek call 22812 function stdin return FILEs; 22813 function stdout return FILEs; 22814 function stderr return FILEs; 22815 -- Streams associated with standard files 22816 -------------------------- 22817 -- Standard C functions -- 22818 -------------------------- 22819 -- The functions selected below are ones that are 22820 -- available in UNIX (but not necessarily in ANSI C). 22821 -- These are very thin interfaces 22822 -- which copy exactly the C headers. For more 22823 -- documentation on these functions, see the Microsoft C 22824 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22825 -- ISBN 1-55615-225-6), which includes useful information 22826 -- on system compatibility. 22827 procedure clearerr (stream : FILEs); 22828 function fclose (stream : FILEs) return int; 22829 function fdopen (handle : int; mode : chars) return FILEs; 22830 function feof (stream : FILEs) return int; 22831 function ferror (stream : FILEs) return int; 22832 function fflush (stream : FILEs) return int; 22833 function fgetc (stream : FILEs) return int; 22834 function fgets (strng : chars; n : int; stream : FILEs) 22835 return chars; 22836 function fileno (stream : FILEs) return int; 22837 function fopen (filename : chars; Mode : chars) 22838 return FILEs; 22839 -- Note: to maintain target independence, use 22840 -- text_translation_required, a boolean variable defined in 22841 -- a-sysdep.c to deal with the target dependent text 22842 -- translation requirement. If this variable is set, 22843 -- then b/t should be appended to the standard mode 22844 -- argument to set the text translation mode off or on 22845 -- as required. 22846 function fputc (C : int; stream : FILEs) return int; 22847 function fputs (Strng : chars; Stream : FILEs) return int; 22848 function fread 22849 (buffer : voids; 22850 size : size_t; 22851 count : size_t; 22852 stream : FILEs) 22853 return size_t; 22854 function freopen 22855 (filename : chars; 22856 mode : chars; 22857 stream : FILEs) 22858 return FILEs; 22859 function fseek 22860 (stream : FILEs; 22861 offset : long; 22862 origin : int) 22863 return int; 22864 function ftell (stream : FILEs) return long; 22865 function fwrite 22866 (buffer : voids; 22867 size : size_t; 22868 count : size_t; 22869 stream : FILEs) 22870 return size_t; 22871 function isatty (handle : int) return int; 22872 procedure mktemp (template : chars); 22873 -- The return value (which is just a pointer to template) 22874 -- is discarded 22875 procedure rewind (stream : FILEs); 22876 function rmtmp return int; 22877 function setvbuf 22878 (stream : FILEs; 22879 buffer : chars; 22880 mode : int; 22881 size : size_t) 22882 return int; 22883 22884 function tmpfile return FILEs; 22885 function ungetc (c : int; stream : FILEs) return int; 22886 function unlink (filename : chars) return int; 22887 --------------------- 22888 -- Extra functions -- 22889 --------------------- 22890 -- These functions supply slightly thicker bindings than 22891 -- those above. They are derived from functions in the 22892 -- C Run-Time Library, but may do a bit more work than 22893 -- just directly calling one of the Library functions. 22894 function is_regular_file (handle : int) return int; 22895 -- Tests if given handle is for a regular file (result 1) 22896 -- or for a non-regular file (pipe or device, result 0). 22897 --------------------------------- 22898 -- Control of Text/Binary Mode -- 22899 --------------------------------- 22900 -- If text_translation_required is true, then the following 22901 -- functions may be used to dynamically switch a file from 22902 -- binary to text mode or vice versa. These functions have 22903 -- no effect if text_translation_required is false (i.e., in 22904 -- normal UNIX mode). Use fileno to get a stream handle. 22905 procedure set_binary_mode (handle : int); 22906 procedure set_text_mode (handle : int); 22907 ---------------------------- 22908 -- Full Path Name support -- 22909 ---------------------------- 22910 procedure full_name (nam : chars; buffer : chars); 22911 -- Given a NUL terminated string representing a file 22912 -- name, returns in buffer a NUL terminated string 22913 -- representing the full path name for the file name. 22914 -- On systems where it is relevant the drive is also 22915 -- part of the full path name. It is the responsibility 22916 -- of the caller to pass an actual parameter for buffer 22917 -- that is big enough for any full path name. Use 22918 -- max_path_len given below as the size of buffer. 22919 max_path_len : integer; 22920 -- Maximum length of an allowable full path name on the 22921 -- system, including a terminating NUL character. 22922end Interfaces.C_Streams; 22923@end example 22924 22925@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 22926@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d0}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d1} 22927@section Interfacing to C Streams 22928 22929 22930The packages in this section permit interfacing Ada files to C Stream 22931operations. 22932 22933@example 22934with Interfaces.C_Streams; 22935package Ada.Sequential_IO.C_Streams is 22936 function C_Stream (F : File_Type) 22937 return Interfaces.C_Streams.FILEs; 22938 procedure Open 22939 (File : in out File_Type; 22940 Mode : in File_Mode; 22941 C_Stream : in Interfaces.C_Streams.FILEs; 22942 Form : in String := ""); 22943end Ada.Sequential_IO.C_Streams; 22944 22945 with Interfaces.C_Streams; 22946 package Ada.Direct_IO.C_Streams is 22947 function C_Stream (F : File_Type) 22948 return Interfaces.C_Streams.FILEs; 22949 procedure Open 22950 (File : in out File_Type; 22951 Mode : in File_Mode; 22952 C_Stream : in Interfaces.C_Streams.FILEs; 22953 Form : in String := ""); 22954 end Ada.Direct_IO.C_Streams; 22955 22956 with Interfaces.C_Streams; 22957 package Ada.Text_IO.C_Streams is 22958 function C_Stream (F : File_Type) 22959 return Interfaces.C_Streams.FILEs; 22960 procedure Open 22961 (File : in out File_Type; 22962 Mode : in File_Mode; 22963 C_Stream : in Interfaces.C_Streams.FILEs; 22964 Form : in String := ""); 22965 end Ada.Text_IO.C_Streams; 22966 22967 with Interfaces.C_Streams; 22968 package Ada.Wide_Text_IO.C_Streams is 22969 function C_Stream (F : File_Type) 22970 return Interfaces.C_Streams.FILEs; 22971 procedure Open 22972 (File : in out File_Type; 22973 Mode : in File_Mode; 22974 C_Stream : in Interfaces.C_Streams.FILEs; 22975 Form : in String := ""); 22976end Ada.Wide_Text_IO.C_Streams; 22977 22978 with Interfaces.C_Streams; 22979 package Ada.Wide_Wide_Text_IO.C_Streams is 22980 function C_Stream (F : File_Type) 22981 return Interfaces.C_Streams.FILEs; 22982 procedure Open 22983 (File : in out File_Type; 22984 Mode : in File_Mode; 22985 C_Stream : in Interfaces.C_Streams.FILEs; 22986 Form : in String := ""); 22987end Ada.Wide_Wide_Text_IO.C_Streams; 22988 22989with Interfaces.C_Streams; 22990package Ada.Stream_IO.C_Streams is 22991 function C_Stream (F : File_Type) 22992 return Interfaces.C_Streams.FILEs; 22993 procedure Open 22994 (File : in out File_Type; 22995 Mode : in File_Mode; 22996 C_Stream : in Interfaces.C_Streams.FILEs; 22997 Form : in String := ""); 22998end Ada.Stream_IO.C_Streams; 22999@end example 23000 23001In each of these six packages, the @code{C_Stream} function obtains the 23002@code{FILE} pointer from a currently opened Ada file. It is then 23003possible to use the @code{Interfaces.C_Streams} package to operate on 23004this stream, or the stream can be passed to a C program which can 23005operate on it directly. Of course the program is responsible for 23006ensuring that only appropriate sequences of operations are executed. 23007 23008One particular use of relevance to an Ada program is that the 23009@code{setvbuf} function can be used to control the buffering of the 23010stream used by an Ada file. In the absence of such a call the standard 23011default buffering is used. 23012 23013The @code{Open} procedures in these packages open a file giving an 23014existing C Stream instead of a file name. Typically this stream is 23015imported from a C program, allowing an Ada file to operate on an 23016existing C file. 23017 23018@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 23019@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2d2}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d3} 23020@chapter The GNAT Library 23021 23022 23023The GNAT library contains a number of general and special purpose packages. 23024It represents functionality that the GNAT developers have found useful, and 23025which is made available to GNAT users. The packages described here are fully 23026supported, and upwards compatibility will be maintained in future releases, 23027so you can use these facilities with the confidence that the same functionality 23028will be available in future releases. 23029 23030The chapter here simply gives a brief summary of the facilities available. 23031The full documentation is found in the spec file for the package. The full 23032sources of these library packages, including both spec and body, are provided 23033with all GNAT releases. For example, to find out the full specifications of 23034the SPITBOL pattern matching capability, including a full tutorial and 23035extensive examples, look in the @code{g-spipat.ads} file in the library. 23036 23037For each entry here, the package name (as it would appear in a @code{with} 23038clause) is given, followed by the name of the corresponding spec file in 23039parentheses. The packages are children in four hierarchies, @code{Ada}, 23040@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 23041GNAT-specific hierarchy. 23042 23043Note that an application program should only use packages in one of these 23044four hierarchies if the package is defined in the Ada Reference Manual, 23045or is listed in this section of the GNAT Programmers Reference Manual. 23046All other units should be considered internal implementation units and 23047should not be directly @code{with}ed by application code. The use of 23048a @code{with} clause that references one of these internal implementation 23049units makes an application potentially dependent on changes in versions 23050of GNAT, and will generate a warning message. 23051 23052@menu 23053* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 23054* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 23055* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 23056* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 23057* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 23058* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 23059* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 23060* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 23061* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 23062* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 23063* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 23064* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 23065* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 23066* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 23067* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 23068* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 23069* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 23070* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 23071* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 23072* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 23073* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 23074* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 23075* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 23076* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 23077* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 23078* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 23079* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 23080* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 23081* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 23082* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 23083* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 23084* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 23085* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 23086* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 23087* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 23088* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 23089* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 23090* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 23091* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 23092* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 23093* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 23094* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 23095* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 23096* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 23097* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 23098* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 23099* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 23100* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 23101* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 23102* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 23103* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 23104* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 23105* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 23106* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 23107* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 23108* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 23109* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 23110* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 23111* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 23112* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 23113* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 23114* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 23115* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 23116* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 23117* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 23118* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 23119* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 23120* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 23121* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 23122* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 23123* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 23124* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 23125* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 23126* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 23127* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 23128* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 23129* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 23130* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 23131* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 23132* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 23133* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 23134* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 23135* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 23136* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 23137* GNAT.IO (g-io.ads): GNAT IO g-io ads. 23138* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 23139* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 23140* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 23141* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 23142* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 23143* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 23144* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 23145* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 23146* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 23147* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 23148* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 23149* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 23150* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 23151* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 23152* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 23153* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 23154* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 23155* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 23156* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 23157* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 23158* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 23159* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 23160* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 23161* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 23162* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 23163* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 23164* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 23165* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 23166* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 23167* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 23168* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 23169* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 23170* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 23171* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 23172* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 23173* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 23174* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 23175* GNAT.Table (g-table.ads): GNAT Table g-table ads. 23176* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 23177* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 23178* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 23179* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 23180* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 23181* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 23182* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 23183* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 23184* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 23185* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 23186* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 23187* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 23188* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 23189* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 23190* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 23191* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 23192* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 23193* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 23194* System.Assertions (s-assert.ads): System Assertions s-assert ads. 23195* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 23196* System.Memory (s-memory.ads): System Memory s-memory ads. 23197* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 23198* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 23199* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 23200* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 23201* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 23202* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 23203* System.Rident (s-rident.ads): System Rident s-rident ads. 23204* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 23205* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 23206* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 23207* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 23208 23209@end menu 23210 23211@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 23212@anchor{gnat_rm/the_gnat_library id2}@anchor{2d4}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d5} 23213@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 23214 23215 23216@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 23217 23218@geindex Latin_9 constants for Character 23219 23220This child of @code{Ada.Characters} 23221provides a set of definitions corresponding to those in the 23222RM-defined package @code{Ada.Characters.Latin_1} but with the 23223few modifications required for @code{Latin-9} 23224The provision of such a package 23225is specifically authorized by the Ada Reference Manual 23226(RM A.3.3(27)). 23227 23228@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 23229@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d6}@anchor{gnat_rm/the_gnat_library id3}@anchor{2d7} 23230@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 23231 23232 23233@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 23234 23235@geindex Latin_1 constants for Wide_Character 23236 23237This child of @code{Ada.Characters} 23238provides a set of definitions corresponding to those in the 23239RM-defined package @code{Ada.Characters.Latin_1} but with the 23240types of the constants being @code{Wide_Character} 23241instead of @code{Character}. The provision of such a package 23242is specifically authorized by the Ada Reference Manual 23243(RM A.3.3(27)). 23244 23245@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 23246@anchor{gnat_rm/the_gnat_library id4}@anchor{2d8}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2d9} 23247@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 23248 23249 23250@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 23251 23252@geindex Latin_9 constants for Wide_Character 23253 23254This child of @code{Ada.Characters} 23255provides a set of definitions corresponding to those in the 23256GNAT defined package @code{Ada.Characters.Latin_9} but with the 23257types of the constants being @code{Wide_Character} 23258instead of @code{Character}. The provision of such a package 23259is specifically authorized by the Ada Reference Manual 23260(RM A.3.3(27)). 23261 23262@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 23263@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2da}@anchor{gnat_rm/the_gnat_library id5}@anchor{2db} 23264@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 23265 23266 23267@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 23268 23269@geindex Latin_1 constants for Wide_Wide_Character 23270 23271This child of @code{Ada.Characters} 23272provides a set of definitions corresponding to those in the 23273RM-defined package @code{Ada.Characters.Latin_1} but with the 23274types of the constants being @code{Wide_Wide_Character} 23275instead of @code{Character}. The provision of such a package 23276is specifically authorized by the Ada Reference Manual 23277(RM A.3.3(27)). 23278 23279@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 23280@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2dc}@anchor{gnat_rm/the_gnat_library id6}@anchor{2dd} 23281@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 23282 23283 23284@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 23285 23286@geindex Latin_9 constants for Wide_Wide_Character 23287 23288This child of @code{Ada.Characters} 23289provides a set of definitions corresponding to those in the 23290GNAT defined package @code{Ada.Characters.Latin_9} but with the 23291types of the constants being @code{Wide_Wide_Character} 23292instead of @code{Character}. The provision of such a package 23293is specifically authorized by the Ada Reference Manual 23294(RM A.3.3(27)). 23295 23296@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 23297@anchor{gnat_rm/the_gnat_library id7}@anchor{2de}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2df} 23298@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 23299 23300 23301@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 23302 23303@geindex Formal container for doubly linked lists 23304 23305This child of @code{Ada.Containers} defines a modified version of the 23306Ada 2005 container for doubly linked lists, meant to facilitate formal 23307verification of code using such containers. The specification of this 23308unit is compatible with SPARK 2014. 23309 23310Note that although this container was designed with formal verification 23311in mind, it may well be generally useful in that it is a simplified more 23312efficient version than the one defined in the standard. In particular it 23313does not have the complex overhead required to detect cursor tampering. 23314 23315@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 23316@anchor{gnat_rm/the_gnat_library id8}@anchor{2e0}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2e1} 23317@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 23318 23319 23320@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 23321 23322@geindex Formal container for hashed maps 23323 23324This child of @code{Ada.Containers} defines a modified version of the 23325Ada 2005 container for hashed maps, meant to facilitate formal 23326verification of code using such containers. The specification of this 23327unit is compatible with SPARK 2014. 23328 23329Note that although this container was designed with formal verification 23330in mind, it may well be generally useful in that it is a simplified more 23331efficient version than the one defined in the standard. In particular it 23332does not have the complex overhead required to detect cursor tampering. 23333 23334@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 23335@anchor{gnat_rm/the_gnat_library id9}@anchor{2e2}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2e3} 23336@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 23337 23338 23339@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 23340 23341@geindex Formal container for hashed sets 23342 23343This child of @code{Ada.Containers} defines a modified version of the 23344Ada 2005 container for hashed sets, meant to facilitate formal 23345verification of code using such containers. The specification of this 23346unit is compatible with SPARK 2014. 23347 23348Note that although this container was designed with formal verification 23349in mind, it may well be generally useful in that it is a simplified more 23350efficient version than the one defined in the standard. In particular it 23351does not have the complex overhead required to detect cursor tampering. 23352 23353@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 23354@anchor{gnat_rm/the_gnat_library id10}@anchor{2e4}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e5} 23355@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 23356 23357 23358@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 23359 23360@geindex Formal container for ordered maps 23361 23362This child of @code{Ada.Containers} defines a modified version of the 23363Ada 2005 container for ordered maps, meant to facilitate formal 23364verification of code using such containers. The specification of this 23365unit is compatible with SPARK 2014. 23366 23367Note that although this container was designed with formal verification 23368in mind, it may well be generally useful in that it is a simplified more 23369efficient version than the one defined in the standard. In particular it 23370does not have the complex overhead required to detect cursor tampering. 23371 23372@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 23373@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e6}@anchor{gnat_rm/the_gnat_library id11}@anchor{2e7} 23374@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 23375 23376 23377@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 23378 23379@geindex Formal container for ordered sets 23380 23381This child of @code{Ada.Containers} defines a modified version of the 23382Ada 2005 container for ordered sets, meant to facilitate formal 23383verification of code using such containers. The specification of this 23384unit is compatible with SPARK 2014. 23385 23386Note that although this container was designed with formal verification 23387in mind, it may well be generally useful in that it is a simplified more 23388efficient version than the one defined in the standard. In particular it 23389does not have the complex overhead required to detect cursor tampering. 23390 23391@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 23392@anchor{gnat_rm/the_gnat_library id12}@anchor{2e8}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2e9} 23393@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 23394 23395 23396@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 23397 23398@geindex Formal container for vectors 23399 23400This child of @code{Ada.Containers} defines a modified version of the 23401Ada 2005 container for vectors, meant to facilitate formal 23402verification of code using such containers. The specification of this 23403unit is compatible with SPARK 2014. 23404 23405Note that although this container was designed with formal verification 23406in mind, it may well be generally useful in that it is a simplified more 23407efficient version than the one defined in the standard. In particular it 23408does not have the complex overhead required to detect cursor tampering. 23409 23410@node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library 23411@anchor{gnat_rm/the_gnat_library id13}@anchor{2ea}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2eb} 23412@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 23413 23414 23415@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 23416 23417@geindex Formal container for vectors 23418 23419This child of @code{Ada.Containers} defines a modified version of the 23420Ada 2005 container for vectors of indefinite elements, meant to 23421facilitate formal verification of code using such containers. The 23422specification of this unit is compatible with SPARK 2014. 23423 23424Note that although this container was designed with formal verification 23425in mind, it may well be generally useful in that it is a simplified more 23426efficient version than the one defined in the standard. In particular it 23427does not have the complex overhead required to detect cursor tampering. 23428 23429@node Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Functional_Sets a-cofuse ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library 23430@anchor{gnat_rm/the_gnat_library id14}@anchor{2ec}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ed} 23431@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) 23432 23433 23434@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) 23435 23436@geindex Functional vectors 23437 23438This child of @code{Ada.Containers} defines immutable vectors. These 23439containers are unbounded and may contain indefinite elements. Furthermore, to 23440be usable in every context, they are neither controlled nor limited. As they 23441are functional, that is, no primitives are provided which would allow modifying 23442an existing container, these containers can still be used safely. 23443 23444Their API features functions creating new containers from existing ones. 23445As a consequence, these containers are highly inefficient. They are also 23446memory consuming, as the allocated memory is not reclaimed when the container 23447is no longer referenced. Thus, they should in general be used in ghost code 23448and annotations, so that they can be removed from the final executable. The 23449specification of this unit is compatible with SPARK 2014. 23450 23451@node Ada Containers Functional_Sets a-cofuse ads,Ada Containers Functional_Maps a-cofuma ads,Ada Containers Functional_Vectors a-cofuve ads,The GNAT Library 23452@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2ee}@anchor{gnat_rm/the_gnat_library id15}@anchor{2ef} 23453@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) 23454 23455 23456@geindex Ada.Containers.Functional_Sets (a-cofuse.ads) 23457 23458@geindex Functional sets 23459 23460This child of @code{Ada.Containers} defines immutable sets. These containers are 23461unbounded and may contain indefinite elements. Furthermore, to be usable in 23462every context, they are neither controlled nor limited. As they are functional, 23463that is, no primitives are provided which would allow modifying an existing 23464container, these containers can still be used safely. 23465 23466Their API features functions creating new containers from existing ones. 23467As a consequence, these containers are highly inefficient. They are also 23468memory consuming, as the allocated memory is not reclaimed when the container 23469is no longer referenced. Thus, they should in general be used in ghost code 23470and annotations, so that they can be removed from the final executable. The 23471specification of this unit is compatible with SPARK 2014. 23472 23473@node Ada Containers Functional_Maps a-cofuma ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Functional_Sets a-cofuse ads,The GNAT Library 23474@anchor{gnat_rm/the_gnat_library id16}@anchor{2f0}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f1} 23475@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) 23476 23477 23478@geindex Ada.Containers.Functional_Maps (a-cofuma.ads) 23479 23480@geindex Functional maps 23481 23482This child of @code{Ada.Containers} defines immutable maps. These containers are 23483unbounded and may contain indefinite elements. Furthermore, to be usable in 23484every context, they are neither controlled nor limited. As they are functional, 23485that is, no primitives are provided which would allow modifying an existing 23486container, these containers can still be used safely. 23487 23488Their API features functions creating new containers from existing ones. 23489As a consequence, these containers are highly inefficient. They are also 23490memory consuming, as the allocated memory is not reclaimed when the container 23491is no longer referenced. Thus, they should in general be used in ghost code 23492and annotations, so that they can be removed from the final executable. The 23493specification of this unit is compatible with SPARK 2014. 23494 23495@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Functional_Maps a-cofuma ads,The GNAT Library 23496@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f2}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f3} 23497@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 23498 23499 23500@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 23501 23502@geindex Formal container for vectors 23503 23504This child of @code{Ada.Containers} defines a modified version of 23505Indefinite_Holders that avoids heap allocation. 23506 23507@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 23508@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f4}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f5} 23509@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) 23510 23511 23512@geindex Ada.Command_Line.Environment (a-colien.ads) 23513 23514@geindex Environment entries 23515 23516This child of @code{Ada.Command_Line} 23517provides a mechanism for obtaining environment values on systems 23518where this concept makes sense. 23519 23520@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 23521@anchor{gnat_rm/the_gnat_library id19}@anchor{2f6}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f7} 23522@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) 23523 23524 23525@geindex Ada.Command_Line.Remove (a-colire.ads) 23526 23527@geindex Removing command line arguments 23528 23529@geindex Command line 23530@geindex argument removal 23531 23532This child of @code{Ada.Command_Line} 23533provides a mechanism for logically removing 23534arguments from the argument list. Once removed, an argument is not visible 23535to further calls on the subprograms in @code{Ada.Command_Line} will not 23536see the removed argument. 23537 23538@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 23539@anchor{gnat_rm/the_gnat_library id20}@anchor{2f8}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2f9} 23540@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 23541 23542 23543@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 23544 23545@geindex Response file for command line 23546 23547@geindex Command line 23548@geindex response file 23549 23550@geindex Command line 23551@geindex handling long command lines 23552 23553This child of @code{Ada.Command_Line} provides a mechanism facilities for 23554getting command line arguments from a text file, called a "response file". 23555Using a response file allow passing a set of arguments to an executable longer 23556than the maximum allowed by the system on the command line. 23557 23558@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 23559@anchor{gnat_rm/the_gnat_library id21}@anchor{2fa}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2fb} 23560@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 23561 23562 23563@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 23564 23565@geindex C Streams 23566@geindex Interfacing with Direct_IO 23567 23568This package provides subprograms that allow interfacing between 23569C streams and @code{Direct_IO}. The stream identifier can be 23570extracted from a file opened on the Ada side, and an Ada file 23571can be constructed from a stream opened on the C side. 23572 23573@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 23574@anchor{gnat_rm/the_gnat_library id22}@anchor{2fc}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2fd} 23575@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 23576 23577 23578@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 23579 23580@geindex Null_Occurrence 23581@geindex testing for 23582 23583This child subprogram provides a way of testing for the null 23584exception occurrence (@code{Null_Occurrence}) without raising 23585an exception. 23586 23587@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 23588@anchor{gnat_rm/the_gnat_library id23}@anchor{2fe}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ff} 23589@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 23590 23591 23592@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 23593 23594@geindex Null_Occurrence 23595@geindex testing for 23596 23597This child subprogram is used for handling otherwise unhandled 23598exceptions (hence the name last chance), and perform clean ups before 23599terminating the program. Note that this subprogram never returns. 23600 23601@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 23602@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{300}@anchor{gnat_rm/the_gnat_library id24}@anchor{301} 23603@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 23604 23605 23606@geindex Ada.Exceptions.Traceback (a-exctra.ads) 23607 23608@geindex Traceback for Exception Occurrence 23609 23610This child package provides the subprogram (@code{Tracebacks}) to 23611give a traceback array of addresses based on an exception 23612occurrence. 23613 23614@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 23615@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{302}@anchor{gnat_rm/the_gnat_library id25}@anchor{303} 23616@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 23617 23618 23619@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 23620 23621@geindex C Streams 23622@geindex Interfacing with Sequential_IO 23623 23624This package provides subprograms that allow interfacing between 23625C streams and @code{Sequential_IO}. The stream identifier can be 23626extracted from a file opened on the Ada side, and an Ada file 23627can be constructed from a stream opened on the C side. 23628 23629@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 23630@anchor{gnat_rm/the_gnat_library id26}@anchor{304}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{305} 23631@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 23632 23633 23634@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 23635 23636@geindex C Streams 23637@geindex Interfacing with Stream_IO 23638 23639This package provides subprograms that allow interfacing between 23640C streams and @code{Stream_IO}. The stream identifier can be 23641extracted from a file opened on the Ada side, and an Ada file 23642can be constructed from a stream opened on the C side. 23643 23644@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 23645@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{306}@anchor{gnat_rm/the_gnat_library id27}@anchor{307} 23646@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 23647 23648 23649@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 23650 23651@geindex Unbounded_String 23652@geindex IO support 23653 23654@geindex Text_IO 23655@geindex extensions for unbounded strings 23656 23657This package provides subprograms for Text_IO for unbounded 23658strings, avoiding the necessity for an intermediate operation 23659with ordinary strings. 23660 23661@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 23662@anchor{gnat_rm/the_gnat_library id28}@anchor{308}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{309} 23663@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 23664 23665 23666@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 23667 23668@geindex Unbounded_Wide_String 23669@geindex IO support 23670 23671@geindex Text_IO 23672@geindex extensions for unbounded wide strings 23673 23674This package provides subprograms for Text_IO for unbounded 23675wide strings, avoiding the necessity for an intermediate operation 23676with ordinary wide strings. 23677 23678@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 23679@anchor{gnat_rm/the_gnat_library id29}@anchor{30a}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{30b} 23680@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 23681 23682 23683@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 23684 23685@geindex Unbounded_Wide_Wide_String 23686@geindex IO support 23687 23688@geindex Text_IO 23689@geindex extensions for unbounded wide wide strings 23690 23691This package provides subprograms for Text_IO for unbounded 23692wide wide strings, avoiding the necessity for an intermediate operation 23693with ordinary wide wide strings. 23694 23695@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 23696@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{30c}@anchor{gnat_rm/the_gnat_library id30}@anchor{30d} 23697@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 23698 23699 23700@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 23701 23702@geindex C Streams 23703@geindex Interfacing with `@w{`}Text_IO`@w{`} 23704 23705This package provides subprograms that allow interfacing between 23706C streams and @code{Text_IO}. The stream identifier can be 23707extracted from a file opened on the Ada side, and an Ada file 23708can be constructed from a stream opened on the C side. 23709 23710@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 23711@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{30e}@anchor{gnat_rm/the_gnat_library id31}@anchor{30f} 23712@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 23713 23714 23715@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 23716 23717@geindex Text_IO resetting standard files 23718 23719This procedure is used to reset the status of the standard files used 23720by Ada.Text_IO. This is useful in a situation (such as a restart in an 23721embedded application) where the status of the files may change during 23722execution (for example a standard input file may be redefined to be 23723interactive). 23724 23725@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 23726@anchor{gnat_rm/the_gnat_library id32}@anchor{310}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{311} 23727@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 23728 23729 23730@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 23731 23732@geindex Unicode categorization 23733@geindex Wide_Character 23734 23735This package provides subprograms that allow categorization of 23736Wide_Character values according to Unicode categories. 23737 23738@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 23739@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{312}@anchor{gnat_rm/the_gnat_library id33}@anchor{313} 23740@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 23741 23742 23743@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 23744 23745@geindex C Streams 23746@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} 23747 23748This package provides subprograms that allow interfacing between 23749C streams and @code{Wide_Text_IO}. The stream identifier can be 23750extracted from a file opened on the Ada side, and an Ada file 23751can be constructed from a stream opened on the C side. 23752 23753@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 23754@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{314}@anchor{gnat_rm/the_gnat_library id34}@anchor{315} 23755@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 23756 23757 23758@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 23759 23760@geindex Wide_Text_IO resetting standard files 23761 23762This procedure is used to reset the status of the standard files used 23763by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 23764embedded application) where the status of the files may change during 23765execution (for example a standard input file may be redefined to be 23766interactive). 23767 23768@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 23769@anchor{gnat_rm/the_gnat_library id35}@anchor{316}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{317} 23770@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 23771 23772 23773@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 23774 23775@geindex Unicode categorization 23776@geindex Wide_Wide_Character 23777 23778This package provides subprograms that allow categorization of 23779Wide_Wide_Character values according to Unicode categories. 23780 23781@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 23782@anchor{gnat_rm/the_gnat_library id36}@anchor{318}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{319} 23783@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 23784 23785 23786@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 23787 23788@geindex C Streams 23789@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} 23790 23791This package provides subprograms that allow interfacing between 23792C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 23793extracted from a file opened on the Ada side, and an Ada file 23794can be constructed from a stream opened on the C side. 23795 23796@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 23797@anchor{gnat_rm/the_gnat_library id37}@anchor{31a}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{31b} 23798@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 23799 23800 23801@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 23802 23803@geindex Wide_Wide_Text_IO resetting standard files 23804 23805This procedure is used to reset the status of the standard files used 23806by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 23807restart in an embedded application) where the status of the files may 23808change during execution (for example a standard input file may be 23809redefined to be interactive). 23810 23811@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 23812@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{31c}@anchor{gnat_rm/the_gnat_library id38}@anchor{31d} 23813@section @code{GNAT.Altivec} (@code{g-altive.ads}) 23814 23815 23816@geindex GNAT.Altivec (g-altive.ads) 23817 23818@geindex AltiVec 23819 23820This is the root package of the GNAT AltiVec binding. It provides 23821definitions of constants and types common to all the versions of the 23822binding. 23823 23824@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 23825@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{31e}@anchor{gnat_rm/the_gnat_library id39}@anchor{31f} 23826@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 23827 23828 23829@geindex GNAT.Altivec.Conversions (g-altcon.ads) 23830 23831@geindex AltiVec 23832 23833This package provides the Vector/View conversion routines. 23834 23835@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23836@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{320}@anchor{gnat_rm/the_gnat_library id40}@anchor{321} 23837@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23838 23839 23840@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23841 23842@geindex AltiVec 23843 23844This package exposes the Ada interface to the AltiVec operations on 23845vector objects. A soft emulation is included by default in the GNAT 23846library. The hard binding is provided as a separate package. This unit 23847is common to both bindings. 23848 23849@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 23850@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{322}@anchor{gnat_rm/the_gnat_library id41}@anchor{323} 23851@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23852 23853 23854@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23855 23856@geindex AltiVec 23857 23858This package exposes the various vector types part of the Ada binding 23859to AltiVec facilities. 23860 23861@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23862@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{324}@anchor{gnat_rm/the_gnat_library id42}@anchor{325} 23863@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23864 23865 23866@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23867 23868@geindex AltiVec 23869 23870This package provides public 'View' data types from/to which private 23871vector representations can be converted via 23872GNAT.Altivec.Conversions. This allows convenient access to individual 23873vector elements and provides a simple way to initialize vector 23874objects. 23875 23876@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23877@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{326}@anchor{gnat_rm/the_gnat_library id43}@anchor{327} 23878@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) 23879 23880 23881@geindex GNAT.Array_Split (g-arrspl.ads) 23882 23883@geindex Array splitter 23884 23885Useful array-manipulation routines: given a set of separators, split 23886an array wherever the separators appear, and provide direct access 23887to the resulting slices. 23888 23889@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 23890@anchor{gnat_rm/the_gnat_library id44}@anchor{328}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{329} 23891@section @code{GNAT.AWK} (@code{g-awk.ads}) 23892 23893 23894@geindex GNAT.AWK (g-awk.ads) 23895 23896@geindex Parsing 23897 23898@geindex AWK 23899 23900Provides AWK-like parsing functions, with an easy interface for parsing one 23901or more files containing formatted data. The file is viewed as a database 23902where each record is a line and a field is a data element in this line. 23903 23904@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library 23905@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32a}@anchor{gnat_rm/the_gnat_library id45}@anchor{32b} 23906@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) 23907 23908 23909@geindex GNAT.Bind_Environment (g-binenv.ads) 23910 23911@geindex Bind environment 23912 23913Provides access to key=value associations captured at bind time. 23914These associations can be specified using the @code{-V} binder command 23915line switch. 23916 23917@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 23918@anchor{gnat_rm/the_gnat_library id46}@anchor{32c}@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{32d} 23919@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) 23920 23921 23922@geindex GNAT.Branch_Prediction (g-brapre.ads) 23923 23924@geindex Branch Prediction 23925 23926Provides routines giving hints to the branch predictor of the code generator. 23927 23928@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library 23929@anchor{gnat_rm/the_gnat_library id47}@anchor{32e}@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{32f} 23930@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 23931 23932 23933@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 23934 23935@geindex Parsing 23936 23937@geindex Bounded Buffers 23938 23939Provides a concurrent generic bounded buffer abstraction. Instances are 23940useful directly or as parts of the implementations of other abstractions, 23941such as mailboxes. 23942 23943@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 23944@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{330}@anchor{gnat_rm/the_gnat_library id48}@anchor{331} 23945@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 23946 23947 23948@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 23949 23950@geindex Parsing 23951 23952@geindex Mailboxes 23953 23954Provides a thread-safe asynchronous intertask mailbox communication facility. 23955 23956@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 23957@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{332}@anchor{gnat_rm/the_gnat_library id49}@anchor{333} 23958@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 23959 23960 23961@geindex GNAT.Bubble_Sort (g-bubsor.ads) 23962 23963@geindex Sorting 23964 23965@geindex Bubble sort 23966 23967Provides a general implementation of bubble sort usable for sorting arbitrary 23968data items. Exchange and comparison procedures are provided by passing 23969access-to-procedure values. 23970 23971@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 23972@anchor{gnat_rm/the_gnat_library id50}@anchor{334}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{335} 23973@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 23974 23975 23976@geindex GNAT.Bubble_Sort_A (g-busora.ads) 23977 23978@geindex Sorting 23979 23980@geindex Bubble sort 23981 23982Provides a general implementation of bubble sort usable for sorting arbitrary 23983data items. Move and comparison procedures are provided by passing 23984access-to-procedure values. This is an older version, retained for 23985compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 23986 23987@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 23988@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{336}@anchor{gnat_rm/the_gnat_library id51}@anchor{337} 23989@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 23990 23991 23992@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 23993 23994@geindex Sorting 23995 23996@geindex Bubble sort 23997 23998Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 23999are provided as generic parameters, this improves efficiency, especially 24000if the procedures can be inlined, at the expense of duplicating code for 24001multiple instantiations. 24002 24003@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 24004@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{338}@anchor{gnat_rm/the_gnat_library id52}@anchor{339} 24005@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 24006 24007 24008@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 24009 24010@geindex UTF-8 representation 24011 24012@geindex Wide characte representations 24013 24014Provides a routine which given a string, reads the start of the string to 24015see whether it is one of the standard byte order marks (BOM's) which signal 24016the encoding of the string. The routine includes detection of special XML 24017sequences for various UCS input formats. 24018 24019@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 24020@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33a}@anchor{gnat_rm/the_gnat_library id53}@anchor{33b} 24021@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 24022 24023 24024@geindex GNAT.Byte_Swapping (g-bytswa.ads) 24025 24026@geindex Byte swapping 24027 24028@geindex Endianness 24029 24030General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 24031Machine-specific implementations are available in some cases. 24032 24033@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 24034@anchor{gnat_rm/the_gnat_library id54}@anchor{33c}@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{33d} 24035@section @code{GNAT.Calendar} (@code{g-calend.ads}) 24036 24037 24038@geindex GNAT.Calendar (g-calend.ads) 24039 24040@geindex Calendar 24041 24042Extends the facilities provided by @code{Ada.Calendar} to include handling 24043of days of the week, an extended @code{Split} and @code{Time_Of} capability. 24044Also provides conversion of @code{Ada.Calendar.Time} values to and from the 24045C @code{timeval} format. 24046 24047@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 24048@anchor{gnat_rm/the_gnat_library id55}@anchor{33e}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{33f} 24049@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 24050 24051 24052@geindex Calendar 24053 24054@geindex Time 24055 24056@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 24057 24058@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 24059@anchor{gnat_rm/the_gnat_library id56}@anchor{340}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{341} 24060@section @code{GNAT.CRC32} (@code{g-crc32.ads}) 24061 24062 24063@geindex GNAT.CRC32 (g-crc32.ads) 24064 24065@geindex CRC32 24066 24067@geindex Cyclic Redundancy Check 24068 24069This package implements the CRC-32 algorithm. For a full description 24070of this algorithm see 24071@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 24072@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 24073Aug. 1988. Sarwate, D.V. 24074 24075@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 24076@anchor{gnat_rm/the_gnat_library id57}@anchor{342}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{343} 24077@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) 24078 24079 24080@geindex GNAT.Case_Util (g-casuti.ads) 24081 24082@geindex Casing utilities 24083 24084@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) 24085 24086A set of simple routines for handling upper and lower casing of strings 24087without the overhead of the full casing tables 24088in @code{Ada.Characters.Handling}. 24089 24090@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 24091@anchor{gnat_rm/the_gnat_library id58}@anchor{344}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{345} 24092@section @code{GNAT.CGI} (@code{g-cgi.ads}) 24093 24094 24095@geindex GNAT.CGI (g-cgi.ads) 24096 24097@geindex CGI (Common Gateway Interface) 24098 24099This is a package for interfacing a GNAT program with a Web server via the 24100Common Gateway Interface (CGI). Basically this package parses the CGI 24101parameters, which are a set of key/value pairs sent by the Web server. It 24102builds a table whose index is the key and provides some services to deal 24103with this table. 24104 24105@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 24106@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{346}@anchor{gnat_rm/the_gnat_library id59}@anchor{347} 24107@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 24108 24109 24110@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 24111 24112@geindex CGI (Common Gateway Interface) cookie support 24113 24114@geindex Cookie support in CGI 24115 24116This is a package to interface a GNAT program with a Web server via the 24117Common Gateway Interface (CGI). It exports services to deal with Web 24118cookies (piece of information kept in the Web client software). 24119 24120@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 24121@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{348}@anchor{gnat_rm/the_gnat_library id60}@anchor{349} 24122@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 24123 24124 24125@geindex GNAT.CGI.Debug (g-cgideb.ads) 24126 24127@geindex CGI (Common Gateway Interface) debugging 24128 24129This is a package to help debugging CGI (Common Gateway Interface) 24130programs written in Ada. 24131 24132@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 24133@anchor{gnat_rm/the_gnat_library id61}@anchor{34a}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34b} 24134@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) 24135 24136 24137@geindex GNAT.Command_Line (g-comlin.ads) 24138 24139@geindex Command line 24140 24141Provides a high level interface to @code{Ada.Command_Line} facilities, 24142including the ability to scan for named switches with optional parameters 24143and expand file names using wildcard notations. 24144 24145@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 24146@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id62}@anchor{34d} 24147@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) 24148 24149 24150@geindex GNAT.Compiler_Version (g-comver.ads) 24151 24152@geindex Compiler Version 24153 24154@geindex Version 24155@geindex of compiler 24156 24157Provides a routine for obtaining the version of the compiler used to 24158compile the program. More accurately this is the version of the binder 24159used to bind the program (this will normally be the same as the version 24160of the compiler if a consistent tool set is used to compile all units 24161of a partition). 24162 24163@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 24164@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{34e}@anchor{gnat_rm/the_gnat_library id63}@anchor{34f} 24165@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 24166 24167 24168@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 24169 24170@geindex Interrupt 24171 24172Provides a simple interface to handle Ctrl-C keyboard events. 24173 24174@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 24175@anchor{gnat_rm/the_gnat_library id64}@anchor{350}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{351} 24176@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) 24177 24178 24179@geindex GNAT.Current_Exception (g-curexc.ads) 24180 24181@geindex Current exception 24182 24183@geindex Exception retrieval 24184 24185Provides access to information on the current exception that has been raised 24186without the need for using the Ada 95 / Ada 2005 exception choice parameter 24187specification syntax. 24188This is particularly useful in simulating typical facilities for 24189obtaining information about exceptions provided by Ada 83 compilers. 24190 24191@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 24192@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{352}@anchor{gnat_rm/the_gnat_library id65}@anchor{353} 24193@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 24194 24195 24196@geindex GNAT.Debug_Pools (g-debpoo.ads) 24197 24198@geindex Debugging 24199 24200@geindex Debug pools 24201 24202@geindex Memory corruption debugging 24203 24204Provide a debugging storage pools that helps tracking memory corruption 24205problems. 24206See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}. 24207 24208@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 24209@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{354}@anchor{gnat_rm/the_gnat_library id66}@anchor{355} 24210@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 24211 24212 24213@geindex GNAT.Debug_Utilities (g-debuti.ads) 24214 24215@geindex Debugging 24216 24217Provides a few useful utilities for debugging purposes, including conversion 24218to and from string images of address values. Supports both C and Ada formats 24219for hexadecimal literals. 24220 24221@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 24222@anchor{gnat_rm/the_gnat_library id67}@anchor{356}@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{357} 24223@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) 24224 24225 24226@geindex GNAT.Decode_String (g-decstr.ads) 24227 24228@geindex Decoding strings 24229 24230@geindex String decoding 24231 24232@geindex Wide character encoding 24233 24234@geindex UTF-8 24235 24236@geindex Unicode 24237 24238A generic package providing routines for decoding wide character and wide wide 24239character strings encoded as sequences of 8-bit characters using a specified 24240encoding method. Includes validation routines, and also routines for stepping 24241to next or previous encoded character in an encoded string. 24242Useful in conjunction with Unicode character coding. Note there is a 24243preinstantiation for UTF-8. See next entry. 24244 24245@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 24246@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{358}@anchor{gnat_rm/the_gnat_library id68}@anchor{359} 24247@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 24248 24249 24250@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 24251 24252@geindex Decoding strings 24253 24254@geindex Decoding UTF-8 strings 24255 24256@geindex UTF-8 string decoding 24257 24258@geindex Wide character decoding 24259 24260@geindex UTF-8 24261 24262@geindex Unicode 24263 24264A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 24265 24266@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 24267@anchor{gnat_rm/the_gnat_library id69}@anchor{35a}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35b} 24268@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) 24269 24270 24271@geindex GNAT.Directory_Operations (g-dirope.ads) 24272 24273@geindex Directory operations 24274 24275Provides a set of routines for manipulating directories, including changing 24276the current directory, making new directories, and scanning the files in a 24277directory. 24278 24279@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 24280@anchor{gnat_rm/the_gnat_library id70}@anchor{35c}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{35d} 24281@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 24282 24283 24284@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 24285 24286@geindex Directory operations iteration 24287 24288A child unit of GNAT.Directory_Operations providing additional operations 24289for iterating through directories. 24290 24291@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 24292@anchor{gnat_rm/the_gnat_library id71}@anchor{35e}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{35f} 24293@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 24294 24295 24296@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 24297 24298@geindex Hash tables 24299 24300A generic implementation of hash tables that can be used to hash arbitrary 24301data. Provided in two forms, a simple form with built in hash functions, 24302and a more complex form in which the hash function is supplied. 24303 24304This package provides a facility similar to that of @code{GNAT.HTable}, 24305except that this package declares a type that can be used to define 24306dynamic instances of the hash table, while an instantiation of 24307@code{GNAT.HTable} creates a single instance of the hash table. 24308 24309@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 24310@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{360}@anchor{gnat_rm/the_gnat_library id72}@anchor{361} 24311@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 24312 24313 24314@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 24315 24316@geindex Table implementation 24317 24318@geindex Arrays 24319@geindex extendable 24320 24321A generic package providing a single dimension array abstraction where the 24322length of the array can be dynamically modified. 24323 24324This package provides a facility similar to that of @code{GNAT.Table}, 24325except that this package declares a type that can be used to define 24326dynamic instances of the table, while an instantiation of 24327@code{GNAT.Table} creates a single instance of the table type. 24328 24329@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 24330@anchor{gnat_rm/the_gnat_library id73}@anchor{362}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{363} 24331@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) 24332 24333 24334@geindex GNAT.Encode_String (g-encstr.ads) 24335 24336@geindex Encoding strings 24337 24338@geindex String encoding 24339 24340@geindex Wide character encoding 24341 24342@geindex UTF-8 24343 24344@geindex Unicode 24345 24346A generic package providing routines for encoding wide character and wide 24347wide character strings as sequences of 8-bit characters using a specified 24348encoding method. Useful in conjunction with Unicode character coding. 24349Note there is a preinstantiation for UTF-8. See next entry. 24350 24351@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 24352@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{364}@anchor{gnat_rm/the_gnat_library id74}@anchor{365} 24353@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 24354 24355 24356@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 24357 24358@geindex Encoding strings 24359 24360@geindex Encoding UTF-8 strings 24361 24362@geindex UTF-8 string encoding 24363 24364@geindex Wide character encoding 24365 24366@geindex UTF-8 24367 24368@geindex Unicode 24369 24370A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 24371 24372@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 24373@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{366}@anchor{gnat_rm/the_gnat_library id75}@anchor{367} 24374@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) 24375 24376 24377@geindex GNAT.Exception_Actions (g-excact.ads) 24378 24379@geindex Exception actions 24380 24381Provides callbacks when an exception is raised. Callbacks can be registered 24382for specific exceptions, or when any exception is raised. This 24383can be used for instance to force a core dump to ease debugging. 24384 24385@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library 24386@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{368}@anchor{gnat_rm/the_gnat_library id76}@anchor{369} 24387@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) 24388 24389 24390@geindex GNAT.Exception_Traces (g-exctra.ads) 24391 24392@geindex Exception traces 24393 24394@geindex Debugging 24395 24396Provides an interface allowing to control automatic output upon exception 24397occurrences. 24398 24399@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 24400@anchor{gnat_rm/the_gnat_library id77}@anchor{36a}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36b} 24401@section @code{GNAT.Exceptions} (@code{g-except.ads}) 24402 24403 24404@geindex GNAT.Exceptions (g-except.ads) 24405 24406@geindex Exceptions 24407@geindex Pure 24408 24409@geindex Pure packages 24410@geindex exceptions 24411 24412Normally it is not possible to raise an exception with 24413a message from a subprogram in a pure package, since the 24414necessary types and subprograms are in @code{Ada.Exceptions} 24415which is not a pure unit. @code{GNAT.Exceptions} provides a 24416facility for getting around this limitation for a few 24417predefined exceptions, and for example allow raising 24418@code{Constraint_Error} with a message from a pure subprogram. 24419 24420@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library 24421@anchor{gnat_rm/the_gnat_library id78}@anchor{36c}@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{36d} 24422@section @code{GNAT.Expect} (@code{g-expect.ads}) 24423 24424 24425@geindex GNAT.Expect (g-expect.ads) 24426 24427Provides a set of subprograms similar to what is available 24428with the standard Tcl Expect tool. 24429It allows you to easily spawn and communicate with an external process. 24430You can send commands or inputs to the process, and compare the output 24431with some expected regular expression. Currently @code{GNAT.Expect} 24432is implemented on all native GNAT ports. 24433It is not implemented for cross ports, and in particular is not 24434implemented for VxWorks or LynxOS. 24435 24436@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 24437@anchor{gnat_rm/the_gnat_library id79}@anchor{36e}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{36f} 24438@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) 24439 24440 24441@geindex GNAT.Expect.TTY (g-exptty.ads) 24442 24443As GNAT.Expect but using pseudo-terminal. 24444Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 24445ports. It is not implemented for cross ports, and 24446in particular is not implemented for VxWorks or LynxOS. 24447 24448@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 24449@anchor{gnat_rm/the_gnat_library id80}@anchor{370}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{371} 24450@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) 24451 24452 24453@geindex GNAT.Float_Control (g-flocon.ads) 24454 24455@geindex Floating-Point Processor 24456 24457Provides an interface for resetting the floating-point processor into the 24458mode required for correct semantic operation in Ada. Some third party 24459library calls may cause this mode to be modified, and the Reset procedure 24460in this package can be used to reestablish the required mode. 24461 24462@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 24463@anchor{gnat_rm/the_gnat_library id81}@anchor{372}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{373} 24464@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) 24465 24466 24467@geindex GNAT.Formatted_String (g-forstr.ads) 24468 24469@geindex Formatted String 24470 24471Provides support for C/C++ printf() formatted strings. The format is 24472copied from the printf() routine and should therefore gives identical 24473output. Some generic routines are provided to be able to use types 24474derived from Integer, Float or enumerations as values for the 24475formatted string. 24476 24477@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 24478@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{374}@anchor{gnat_rm/the_gnat_library id82}@anchor{375} 24479@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) 24480 24481 24482@geindex GNAT.Heap_Sort (g-heasor.ads) 24483 24484@geindex Sorting 24485 24486Provides a general implementation of heap sort usable for sorting arbitrary 24487data items. Exchange and comparison procedures are provided by passing 24488access-to-procedure values. The algorithm used is a modified heap sort 24489that performs approximately N*log(N) comparisons in the worst case. 24490 24491@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 24492@anchor{gnat_rm/the_gnat_library id83}@anchor{376}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{377} 24493@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 24494 24495 24496@geindex GNAT.Heap_Sort_A (g-hesora.ads) 24497 24498@geindex Sorting 24499 24500Provides a general implementation of heap sort usable for sorting arbitrary 24501data items. Move and comparison procedures are provided by passing 24502access-to-procedure values. The algorithm used is a modified heap sort 24503that performs approximately N*log(N) comparisons in the worst case. 24504This differs from @code{GNAT.Heap_Sort} in having a less convenient 24505interface, but may be slightly more efficient. 24506 24507@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 24508@anchor{gnat_rm/the_gnat_library id84}@anchor{378}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{379} 24509@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 24510 24511 24512@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 24513 24514@geindex Sorting 24515 24516Similar to @code{Heap_Sort_A} except that the move and sorting procedures 24517are provided as generic parameters, this improves efficiency, especially 24518if the procedures can be inlined, at the expense of duplicating code for 24519multiple instantiations. 24520 24521@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 24522@anchor{gnat_rm/the_gnat_library id85}@anchor{37a}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37b} 24523@section @code{GNAT.HTable} (@code{g-htable.ads}) 24524 24525 24526@geindex GNAT.HTable (g-htable.ads) 24527 24528@geindex Hash tables 24529 24530A generic implementation of hash tables that can be used to hash arbitrary 24531data. Provides two approaches, one a simple static approach, and the other 24532allowing arbitrary dynamic hash tables. 24533 24534@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 24535@anchor{gnat_rm/the_gnat_library id86}@anchor{37c}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{37d} 24536@section @code{GNAT.IO} (@code{g-io.ads}) 24537 24538 24539@geindex GNAT.IO (g-io.ads) 24540 24541@geindex Simple I/O 24542 24543@geindex Input/Output facilities 24544 24545A simple preelaborable input-output package that provides a subset of 24546simple Text_IO functions for reading characters and strings from 24547Standard_Input, and writing characters, strings and integers to either 24548Standard_Output or Standard_Error. 24549 24550@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 24551@anchor{gnat_rm/the_gnat_library id87}@anchor{37e}@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{37f} 24552@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) 24553 24554 24555@geindex GNAT.IO_Aux (g-io_aux.ads) 24556 24557@geindex Text_IO 24558 24559@geindex Input/Output facilities 24560 24561Provides some auxiliary functions for use with Text_IO, including a test 24562for whether a file exists, and functions for reading a line of text. 24563 24564@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 24565@anchor{gnat_rm/the_gnat_library id88}@anchor{380}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{381} 24566@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) 24567 24568 24569@geindex GNAT.Lock_Files (g-locfil.ads) 24570 24571@geindex File locking 24572 24573@geindex Locking using files 24574 24575Provides a general interface for using files as locks. Can be used for 24576providing program level synchronization. 24577 24578@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 24579@anchor{gnat_rm/the_gnat_library id89}@anchor{382}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{383} 24580@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 24581 24582 24583@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 24584 24585@geindex Random number generation 24586 24587The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 24588a modified version of the Blum-Blum-Shub generator. 24589 24590@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 24591@anchor{gnat_rm/the_gnat_library id90}@anchor{384}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{385} 24592@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 24593 24594 24595@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 24596 24597@geindex Random number generation 24598 24599The original implementation of @code{Ada.Numerics.Float_Random}. Uses 24600a modified version of the Blum-Blum-Shub generator. 24601 24602@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 24603@anchor{gnat_rm/the_gnat_library id91}@anchor{386}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{387} 24604@section @code{GNAT.MD5} (@code{g-md5.ads}) 24605 24606 24607@geindex GNAT.MD5 (g-md5.ads) 24608 24609@geindex Message Digest MD5 24610 24611Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 24612the HMAC-MD5 message authentication function as described in RFC 2104 and 24613FIPS PUB 198. 24614 24615@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 24616@anchor{gnat_rm/the_gnat_library id92}@anchor{388}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{389} 24617@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) 24618 24619 24620@geindex GNAT.Memory_Dump (g-memdum.ads) 24621 24622@geindex Dump Memory 24623 24624Provides a convenient routine for dumping raw memory to either the 24625standard output or standard error files. Uses GNAT.IO for actual 24626output. 24627 24628@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 24629@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38a}@anchor{gnat_rm/the_gnat_library id93}@anchor{38b} 24630@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 24631 24632 24633@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 24634 24635@geindex Exception 24636@geindex obtaining most recent 24637 24638Provides access to the most recently raised exception. Can be used for 24639various logging purposes, including duplicating functionality of some 24640Ada 83 implementation dependent extensions. 24641 24642@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 24643@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{38c}@anchor{gnat_rm/the_gnat_library id94}@anchor{38d} 24644@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) 24645 24646 24647@geindex GNAT.OS_Lib (g-os_lib.ads) 24648 24649@geindex Operating System interface 24650 24651@geindex Spawn capability 24652 24653Provides a range of target independent operating system interface functions, 24654including time/date management, file operations, subprocess management, 24655including a portable spawn procedure, and access to environment variables 24656and error return codes. 24657 24658@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 24659@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id95}@anchor{38f} 24660@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 24661 24662 24663@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 24664 24665@geindex Hash functions 24666 24667Provides a generator of static minimal perfect hash functions. No 24668collisions occur and each item can be retrieved from the table in one 24669probe (perfect property). The hash table size corresponds to the exact 24670size of the key set and no larger (minimal property). The key set has to 24671be know in advance (static property). The hash functions are also order 24672preserving. If w2 is inserted after w1 in the generator, their 24673hashcode are in the same order. These hashing functions are very 24674convenient for use with realtime applications. 24675 24676@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 24677@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id96}@anchor{391} 24678@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) 24679 24680 24681@geindex GNAT.Random_Numbers (g-rannum.ads) 24682 24683@geindex Random number generation 24684 24685Provides random number capabilities which extend those available in the 24686standard Ada library and are more convenient to use. 24687 24688@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 24689@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{259}@anchor{gnat_rm/the_gnat_library id97}@anchor{392} 24690@section @code{GNAT.Regexp} (@code{g-regexp.ads}) 24691 24692 24693@geindex GNAT.Regexp (g-regexp.ads) 24694 24695@geindex Regular expressions 24696 24697@geindex Pattern matching 24698 24699A simple implementation of regular expressions, using a subset of regular 24700expression syntax copied from familiar Unix style utilities. This is the 24701simplest of the three pattern matching packages provided, and is particularly 24702suitable for 'file globbing' applications. 24703 24704@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 24705@anchor{gnat_rm/the_gnat_library id98}@anchor{393}@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{394} 24706@section @code{GNAT.Registry} (@code{g-regist.ads}) 24707 24708 24709@geindex GNAT.Registry (g-regist.ads) 24710 24711@geindex Windows Registry 24712 24713This is a high level binding to the Windows registry. It is possible to 24714do simple things like reading a key value, creating a new key. For full 24715registry API, but at a lower level of abstraction, refer to the Win32.Winreg 24716package provided with the Win32Ada binding 24717 24718@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 24719@anchor{gnat_rm/the_gnat_library id99}@anchor{395}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{396} 24720@section @code{GNAT.Regpat} (@code{g-regpat.ads}) 24721 24722 24723@geindex GNAT.Regpat (g-regpat.ads) 24724 24725@geindex Regular expressions 24726 24727@geindex Pattern matching 24728 24729A complete implementation of Unix-style regular expression matching, copied 24730from the original V7 style regular expression library written in C by 24731Henry Spencer (and binary compatible with this C library). 24732 24733@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 24734@anchor{gnat_rm/the_gnat_library id100}@anchor{397}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{398} 24735@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 24736 24737 24738@geindex GNAT.Rewrite_Data (g-rewdat.ads) 24739 24740@geindex Rewrite data 24741 24742A unit to rewrite on-the-fly string occurrences in a stream of 24743data. The implementation has a very minimal memory footprint as the 24744full content to be processed is not loaded into memory all at once. This makes 24745this interface usable for large files or socket streams. 24746 24747@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 24748@anchor{gnat_rm/the_gnat_library id101}@anchor{399}@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39a} 24749@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 24750 24751 24752@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 24753 24754@geindex Secondary Stack Info 24755 24756Provide the capability to query the high water mark of the current task's 24757secondary stack. 24758 24759@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 24760@anchor{gnat_rm/the_gnat_library id102}@anchor{39b}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{39c} 24761@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) 24762 24763 24764@geindex GNAT.Semaphores (g-semaph.ads) 24765 24766@geindex Semaphores 24767 24768Provides classic counting and binary semaphores using protected types. 24769 24770@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 24771@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{39d}@anchor{gnat_rm/the_gnat_library id103}@anchor{39e} 24772@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) 24773 24774 24775@geindex GNAT.Serial_Communications (g-sercom.ads) 24776 24777@geindex Serial_Communications 24778 24779Provides a simple interface to send and receive data over a serial 24780port. This is only supported on GNU/Linux and Windows. 24781 24782@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 24783@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{39f}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a0} 24784@section @code{GNAT.SHA1} (@code{g-sha1.ads}) 24785 24786 24787@geindex GNAT.SHA1 (g-sha1.ads) 24788 24789@geindex Secure Hash Algorithm SHA-1 24790 24791Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 24792and RFC 3174, and the HMAC-SHA1 message authentication function as described 24793in RFC 2104 and FIPS PUB 198. 24794 24795@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 24796@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a1}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a2} 24797@section @code{GNAT.SHA224} (@code{g-sha224.ads}) 24798 24799 24800@geindex GNAT.SHA224 (g-sha224.ads) 24801 24802@geindex Secure Hash Algorithm SHA-224 24803 24804Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 24805and the HMAC-SHA224 message authentication function as described 24806in RFC 2104 and FIPS PUB 198. 24807 24808@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 24809@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a3}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a4} 24810@section @code{GNAT.SHA256} (@code{g-sha256.ads}) 24811 24812 24813@geindex GNAT.SHA256 (g-sha256.ads) 24814 24815@geindex Secure Hash Algorithm SHA-256 24816 24817Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 24818and the HMAC-SHA256 message authentication function as described 24819in RFC 2104 and FIPS PUB 198. 24820 24821@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 24822@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3a5}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a6} 24823@section @code{GNAT.SHA384} (@code{g-sha384.ads}) 24824 24825 24826@geindex GNAT.SHA384 (g-sha384.ads) 24827 24828@geindex Secure Hash Algorithm SHA-384 24829 24830Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 24831and the HMAC-SHA384 message authentication function as described 24832in RFC 2104 and FIPS PUB 198. 24833 24834@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 24835@anchor{gnat_rm/the_gnat_library id108}@anchor{3a7}@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a8} 24836@section @code{GNAT.SHA512} (@code{g-sha512.ads}) 24837 24838 24839@geindex GNAT.SHA512 (g-sha512.ads) 24840 24841@geindex Secure Hash Algorithm SHA-512 24842 24843Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 24844and the HMAC-SHA512 message authentication function as described 24845in RFC 2104 and FIPS PUB 198. 24846 24847@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24848@anchor{gnat_rm/the_gnat_library id109}@anchor{3a9}@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3aa} 24849@section @code{GNAT.Signals} (@code{g-signal.ads}) 24850 24851 24852@geindex GNAT.Signals (g-signal.ads) 24853 24854@geindex Signals 24855 24856Provides the ability to manipulate the blocked status of signals on supported 24857targets. 24858 24859@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24860@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3ab}@anchor{gnat_rm/the_gnat_library id110}@anchor{3ac} 24861@section @code{GNAT.Sockets} (@code{g-socket.ads}) 24862 24863 24864@geindex GNAT.Sockets (g-socket.ads) 24865 24866@geindex Sockets 24867 24868A high level and portable interface to develop sockets based applications. 24869This package is based on the sockets thin binding found in 24870@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 24871on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24872the LynxOS cross port. 24873 24874@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24875@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3ad}@anchor{gnat_rm/the_gnat_library id111}@anchor{3ae} 24876@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) 24877 24878 24879@geindex GNAT.Source_Info (g-souinf.ads) 24880 24881@geindex Source Information 24882 24883Provides subprograms that give access to source code information known at 24884compile time, such as the current file name and line number. Also provides 24885subprograms yielding the date and time of the current compilation (like the 24886C macros @code{__DATE__} and @code{__TIME__}) 24887 24888@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 24889@anchor{gnat_rm/the_gnat_library id112}@anchor{3af}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b0} 24890@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) 24891 24892 24893@geindex GNAT.Spelling_Checker (g-speche.ads) 24894 24895@geindex Spell checking 24896 24897Provides a function for determining whether one string is a plausible 24898near misspelling of another string. 24899 24900@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 24901@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b1}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b2} 24902@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 24903 24904 24905@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 24906 24907@geindex Spell checking 24908 24909Provides a generic function that can be instantiated with a string type for 24910determining whether one string is a plausible near misspelling of another 24911string. 24912 24913@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 24914@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b3}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b4} 24915@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 24916 24917 24918@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 24919 24920@geindex SPITBOL pattern matching 24921 24922@geindex Pattern matching 24923 24924A complete implementation of SNOBOL4 style pattern matching. This is the 24925most elaborate of the pattern matching packages provided. It fully duplicates 24926the SNOBOL4 dynamic pattern construction and matching capabilities, using the 24927efficient algorithm developed by Robert Dewar for the SPITBOL system. 24928 24929@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 24930@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3b5}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b6} 24931@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) 24932 24933 24934@geindex GNAT.Spitbol (g-spitbo.ads) 24935 24936@geindex SPITBOL interface 24937 24938The top level package of the collection of SPITBOL-style functionality, this 24939package provides basic SNOBOL4 string manipulation functions, such as 24940Pad, Reverse, Trim, Substr capability, as well as a generic table function 24941useful for constructing arbitrary mappings from strings in the style of 24942the SNOBOL4 TABLE function. 24943 24944@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 24945@anchor{gnat_rm/the_gnat_library id116}@anchor{3b7}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b8} 24946@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 24947 24948 24949@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 24950 24951@geindex Sets of strings 24952 24953@geindex SPITBOL Tables 24954 24955A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24956for type @code{Standard.Boolean}, giving an implementation of sets of 24957string values. 24958 24959@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 24960@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3b9}@anchor{gnat_rm/the_gnat_library id117}@anchor{3ba} 24961@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 24962 24963 24964@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 24965 24966@geindex Integer maps 24967 24968@geindex Maps 24969 24970@geindex SPITBOL Tables 24971 24972A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24973for type @code{Standard.Integer}, giving an implementation of maps 24974from string to integer values. 24975 24976@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 24977@anchor{gnat_rm/the_gnat_library id118}@anchor{3bb}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3bc} 24978@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 24979 24980 24981@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 24982 24983@geindex String maps 24984 24985@geindex Maps 24986 24987@geindex SPITBOL Tables 24988 24989A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 24990a variable length string type, giving an implementation of general 24991maps from strings to strings. 24992 24993@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 24994@anchor{gnat_rm/the_gnat_library id119}@anchor{3bd}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3be} 24995@section @code{GNAT.SSE} (@code{g-sse.ads}) 24996 24997 24998@geindex GNAT.SSE (g-sse.ads) 24999 25000Root of a set of units aimed at offering Ada bindings to a subset of 25001the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 25002targets. It exposes vector component types together with a general 25003introduction to the binding contents and use. 25004 25005@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library 25006@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3bf}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c0} 25007@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 25008 25009 25010@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 25011 25012SSE vector types for use with SSE related intrinsics. 25013 25014@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 25015@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c1}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c2} 25016@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) 25017 25018 25019@geindex GNAT.String_Hash (g-strhas.ads) 25020 25021@geindex Hash functions 25022 25023Provides a generic hash function working on arrays of scalars. Both the scalar 25024type and the hash result type are parameters. 25025 25026@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library 25027@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c3}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c4} 25028@section @code{GNAT.Strings} (@code{g-string.ads}) 25029 25030 25031@geindex GNAT.Strings (g-string.ads) 25032 25033Common String access types and related subprograms. Basically it 25034defines a string access and an array of string access types. 25035 25036@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 25037@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c5}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c6} 25038@section @code{GNAT.String_Split} (@code{g-strspl.ads}) 25039 25040 25041@geindex GNAT.String_Split (g-strspl.ads) 25042 25043@geindex String splitter 25044 25045Useful string manipulation routines: given a set of separators, split 25046a string wherever the separators appear, and provide direct access 25047to the resulting slices. This package is instantiated from 25048@code{GNAT.Array_Split}. 25049 25050@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 25051@anchor{gnat_rm/the_gnat_library id124}@anchor{3c7}@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c8} 25052@section @code{GNAT.Table} (@code{g-table.ads}) 25053 25054 25055@geindex GNAT.Table (g-table.ads) 25056 25057@geindex Table implementation 25058 25059@geindex Arrays 25060@geindex extendable 25061 25062A generic package providing a single dimension array abstraction where the 25063length of the array can be dynamically modified. 25064 25065This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 25066except that this package declares a single instance of the table type, 25067while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 25068used to define dynamic instances of the table. 25069 25070@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 25071@anchor{gnat_rm/the_gnat_library id125}@anchor{3c9}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ca} 25072@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) 25073 25074 25075@geindex GNAT.Task_Lock (g-tasloc.ads) 25076 25077@geindex Task synchronization 25078 25079@geindex Task locking 25080 25081@geindex Locking 25082 25083A very simple facility for locking and unlocking sections of code using a 25084single global task lock. Appropriate for use in situations where contention 25085between tasks is very rarely expected. 25086 25087@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 25088@anchor{gnat_rm/the_gnat_library id126}@anchor{3cb}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3cc} 25089@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) 25090 25091 25092@geindex GNAT.Time_Stamp (g-timsta.ads) 25093 25094@geindex Time stamp 25095 25096@geindex Current time 25097 25098Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 25099represents the current date and time in ISO 8601 format. This is a very simple 25100routine with minimal code and there are no dependencies on any other unit. 25101 25102@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 25103@anchor{gnat_rm/the_gnat_library id127}@anchor{3cd}@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3ce} 25104@section @code{GNAT.Threads} (@code{g-thread.ads}) 25105 25106 25107@geindex GNAT.Threads (g-thread.ads) 25108 25109@geindex Foreign threads 25110 25111@geindex Threads 25112@geindex foreign 25113 25114Provides facilities for dealing with foreign threads which need to be known 25115by the GNAT run-time system. Consult the documentation of this package for 25116further details if your program has threads that are created by a non-Ada 25117environment which then accesses Ada code. 25118 25119@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 25120@anchor{gnat_rm/the_gnat_library id128}@anchor{3cf}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d0} 25121@section @code{GNAT.Traceback} (@code{g-traceb.ads}) 25122 25123 25124@geindex GNAT.Traceback (g-traceb.ads) 25125 25126@geindex Trace back facilities 25127 25128Provides a facility for obtaining non-symbolic traceback information, useful 25129in various debugging situations. 25130 25131@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 25132@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d1}@anchor{gnat_rm/the_gnat_library id129}@anchor{3d2} 25133@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 25134 25135 25136@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 25137 25138@geindex Trace back facilities 25139 25140@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 25141@anchor{gnat_rm/the_gnat_library id130}@anchor{3d3}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d4} 25142@section @code{GNAT.UTF_32} (@code{g-table.ads}) 25143 25144 25145@geindex GNAT.UTF_32 (g-table.ads) 25146 25147@geindex Wide character codes 25148 25149This is a package intended to be used in conjunction with the 25150@code{Wide_Character} type in Ada 95 and the 25151@code{Wide_Wide_Character} type in Ada 2005 (available 25152in @code{GNAT} in Ada 2005 mode). This package contains 25153Unicode categorization routines, as well as lexical 25154categorization routines corresponding to the Ada 2005 25155lexical rules for identifiers and strings, and also a 25156lower case to upper case fold routine corresponding to 25157the Ada 2005 rules for identifier equivalence. 25158 25159@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 25160@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3d5}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d6} 25161@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 25162 25163 25164@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 25165 25166@geindex Spell checking 25167 25168Provides a function for determining whether one wide wide string is a plausible 25169near misspelling of another wide wide string, where the strings are represented 25170using the UTF_32_String type defined in System.Wch_Cnv. 25171 25172@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 25173@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d7}@anchor{gnat_rm/the_gnat_library id132}@anchor{3d8} 25174@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 25175 25176 25177@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 25178 25179@geindex Spell checking 25180 25181Provides a function for determining whether one wide string is a plausible 25182near misspelling of another wide string. 25183 25184@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 25185@anchor{gnat_rm/the_gnat_library id133}@anchor{3d9}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3da} 25186@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 25187 25188 25189@geindex GNAT.Wide_String_Split (g-wistsp.ads) 25190 25191@geindex Wide_String splitter 25192 25193Useful wide string manipulation routines: given a set of separators, split 25194a wide string wherever the separators appear, and provide direct access 25195to the resulting slices. This package is instantiated from 25196@code{GNAT.Array_Split}. 25197 25198@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 25199@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3db}@anchor{gnat_rm/the_gnat_library id134}@anchor{3dc} 25200@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 25201 25202 25203@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 25204 25205@geindex Spell checking 25206 25207Provides a function for determining whether one wide wide string is a plausible 25208near misspelling of another wide wide string. 25209 25210@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 25211@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3dd}@anchor{gnat_rm/the_gnat_library id135}@anchor{3de} 25212@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 25213 25214 25215@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 25216 25217@geindex Wide_Wide_String splitter 25218 25219Useful wide wide string manipulation routines: given a set of separators, split 25220a wide wide string wherever the separators appear, and provide direct access 25221to the resulting slices. This package is instantiated from 25222@code{GNAT.Array_Split}. 25223 25224@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 25225@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3df}@anchor{gnat_rm/the_gnat_library id136}@anchor{3e0} 25226@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) 25227 25228 25229@geindex Interfaces.C.Extensions (i-cexten.ads) 25230 25231This package contains additional C-related definitions, intended 25232for use with either manually or automatically generated bindings 25233to C libraries. 25234 25235@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 25236@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e1}@anchor{gnat_rm/the_gnat_library id137}@anchor{3e2} 25237@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) 25238 25239 25240@geindex Interfaces.C.Streams (i-cstrea.ads) 25241 25242@geindex C streams 25243@geindex interfacing 25244 25245This package is a binding for the most commonly used operations 25246on C streams. 25247 25248@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 25249@anchor{gnat_rm/the_gnat_library id138}@anchor{3e3}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e4} 25250@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 25251 25252 25253@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 25254 25255@geindex IBM Packed Format 25256 25257@geindex Packed Decimal 25258 25259This package provides a set of routines for conversions to and 25260from a packed decimal format compatible with that used on IBM 25261mainframes. 25262 25263@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 25264@anchor{gnat_rm/the_gnat_library id139}@anchor{3e5}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e6} 25265@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) 25266 25267 25268@geindex Interfaces.VxWorks (i-vxwork.ads) 25269 25270@geindex Interfacing to VxWorks 25271 25272@geindex VxWorks 25273@geindex interfacing 25274 25275This package provides a limited binding to the VxWorks API. 25276In particular, it interfaces with the 25277VxWorks hardware interrupt facilities. 25278 25279@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 25280@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e7}@anchor{gnat_rm/the_gnat_library id140}@anchor{3e8} 25281@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) 25282 25283 25284@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) 25285 25286@geindex Interfacing to VxWorks 25287 25288@geindex VxWorks 25289@geindex interfacing 25290 25291This package provides a way for users to replace the use of 25292intConnect() with a custom routine for installing interrupt 25293handlers. 25294 25295@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library 25296@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3e9}@anchor{gnat_rm/the_gnat_library id141}@anchor{3ea} 25297@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 25298 25299 25300@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 25301 25302@geindex Interfacing to VxWorks' I/O 25303 25304@geindex VxWorks 25305@geindex I/O interfacing 25306 25307@geindex VxWorks 25308@geindex Get_Immediate 25309 25310@geindex Get_Immediate 25311@geindex VxWorks 25312 25313This package provides a binding to the ioctl (IO/Control) 25314function of VxWorks, defining a set of option values and 25315function codes. A particular use of this package is 25316to enable the use of Get_Immediate under VxWorks. 25317 25318@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 25319@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3eb}@anchor{gnat_rm/the_gnat_library id142}@anchor{3ec} 25320@section @code{System.Address_Image} (@code{s-addima.ads}) 25321 25322 25323@geindex System.Address_Image (s-addima.ads) 25324 25325@geindex Address image 25326 25327@geindex Image 25328@geindex of an address 25329 25330This function provides a useful debugging 25331function that gives an (implementation dependent) 25332string which identifies an address. 25333 25334@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 25335@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3ed}@anchor{gnat_rm/the_gnat_library id143}@anchor{3ee} 25336@section @code{System.Assertions} (@code{s-assert.ads}) 25337 25338 25339@geindex System.Assertions (s-assert.ads) 25340 25341@geindex Assertions 25342 25343@geindex Assert_Failure 25344@geindex exception 25345 25346This package provides the declaration of the exception raised 25347by an run-time assertion failure, as well as the routine that 25348is used internally to raise this assertion. 25349 25350@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 25351@anchor{gnat_rm/the_gnat_library id144}@anchor{3ef}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f0} 25352@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) 25353 25354 25355@geindex System.Atomic_Counters (s-atocou.ads) 25356 25357This package provides the declaration of an atomic counter type, 25358together with efficient routines (using hardware 25359synchronization primitives) for incrementing, decrementing, 25360and testing of these counters. This package is implemented 25361on most targets, including all Alpha, ia64, PowerPC, SPARC V9, 25362x86, and x86_64 platforms. 25363 25364@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 25365@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f1}@anchor{gnat_rm/the_gnat_library id145}@anchor{3f2} 25366@section @code{System.Memory} (@code{s-memory.ads}) 25367 25368 25369@geindex System.Memory (s-memory.ads) 25370 25371@geindex Memory allocation 25372 25373This package provides the interface to the low level routines used 25374by the generated code for allocation and freeing storage for the 25375default storage pool (analogous to the C routines malloc and free. 25376It also provides a reallocation interface analogous to the C routine 25377realloc. The body of this unit may be modified to provide alternative 25378allocation mechanisms for the default pool, and in addition, direct 25379calls to this unit may be made for low level allocation uses (for 25380example see the body of @code{GNAT.Tables}). 25381 25382@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 25383@anchor{gnat_rm/the_gnat_library id146}@anchor{3f3}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f4} 25384@section @code{System.Multiprocessors} (@code{s-multip.ads}) 25385 25386 25387@geindex System.Multiprocessors (s-multip.ads) 25388 25389@geindex Multiprocessor interface 25390 25391This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25392in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25393technically an implementation-defined addition). 25394 25395@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 25396@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f5}@anchor{gnat_rm/the_gnat_library id147}@anchor{3f6} 25397@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 25398 25399 25400@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 25401 25402@geindex Multiprocessor interface 25403 25404This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25405in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25406technically an implementation-defined addition). 25407 25408@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 25409@anchor{gnat_rm/the_gnat_library id148}@anchor{3f7}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f8} 25410@section @code{System.Partition_Interface} (@code{s-parint.ads}) 25411 25412 25413@geindex System.Partition_Interface (s-parint.ads) 25414 25415@geindex Partition interfacing functions 25416 25417This package provides facilities for partition interfacing. It 25418is used primarily in a distribution context when using Annex E 25419with @code{GLADE}. 25420 25421@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 25422@anchor{gnat_rm/the_gnat_library id149}@anchor{3f9}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3fa} 25423@section @code{System.Pool_Global} (@code{s-pooglo.ads}) 25424 25425 25426@geindex System.Pool_Global (s-pooglo.ads) 25427 25428@geindex Storage pool 25429@geindex global 25430 25431@geindex Global storage pool 25432 25433This package provides a storage pool that is equivalent to the default 25434storage pool used for access types for which no pool is specifically 25435declared. It uses malloc/free to allocate/free and does not attempt to 25436do any automatic reclamation. 25437 25438@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 25439@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3fb}@anchor{gnat_rm/the_gnat_library id150}@anchor{3fc} 25440@section @code{System.Pool_Local} (@code{s-pooloc.ads}) 25441 25442 25443@geindex System.Pool_Local (s-pooloc.ads) 25444 25445@geindex Storage pool 25446@geindex local 25447 25448@geindex Local storage pool 25449 25450This package provides a storage pool that is intended for use with locally 25451defined access types. It uses malloc/free for allocate/free, and maintains 25452a list of allocated blocks, so that all storage allocated for the pool can 25453be freed automatically when the pool is finalized. 25454 25455@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 25456@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3fd}@anchor{gnat_rm/the_gnat_library id151}@anchor{3fe} 25457@section @code{System.Restrictions} (@code{s-restri.ads}) 25458 25459 25460@geindex System.Restrictions (s-restri.ads) 25461 25462@geindex Run-time restrictions access 25463 25464This package provides facilities for accessing at run time 25465the status of restrictions specified at compile time for 25466the partition. Information is available both with regard 25467to actual restrictions specified, and with regard to 25468compiler determined information on which restrictions 25469are violated by one or more packages in the partition. 25470 25471@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 25472@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3ff}@anchor{gnat_rm/the_gnat_library id152}@anchor{400} 25473@section @code{System.Rident} (@code{s-rident.ads}) 25474 25475 25476@geindex System.Rident (s-rident.ads) 25477 25478@geindex Restrictions definitions 25479 25480This package provides definitions of the restrictions 25481identifiers supported by GNAT, and also the format of 25482the restrictions provided in package System.Restrictions. 25483It is not normally necessary to @code{with} this generic package 25484since the necessary instantiation is included in 25485package System.Restrictions. 25486 25487@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 25488@anchor{gnat_rm/the_gnat_library id153}@anchor{401}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{402} 25489@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 25490 25491 25492@geindex System.Strings.Stream_Ops (s-ststop.ads) 25493 25494@geindex Stream operations 25495 25496@geindex String stream operations 25497 25498This package provides a set of stream subprograms for standard string types. 25499It is intended primarily to support implicit use of such subprograms when 25500stream attributes are applied to string types, but the subprograms in this 25501package can be used directly by application programs. 25502 25503@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 25504@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{403}@anchor{gnat_rm/the_gnat_library id154}@anchor{404} 25505@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) 25506 25507 25508@geindex System.Unsigned_Types (s-unstyp.ads) 25509 25510This package contains definitions of standard unsigned types that 25511correspond in size to the standard signed types declared in Standard, 25512and (unlike the types in Interfaces) have corresponding names. It 25513also contains some related definitions for other specialized types 25514used by the compiler in connection with packed array types. 25515 25516@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 25517@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{405}@anchor{gnat_rm/the_gnat_library id155}@anchor{406} 25518@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) 25519 25520 25521@geindex System.Wch_Cnv (s-wchcnv.ads) 25522 25523@geindex Wide Character 25524@geindex Representation 25525 25526@geindex Wide String 25527@geindex Conversion 25528 25529@geindex Representation of wide characters 25530 25531This package provides routines for converting between 25532wide and wide wide characters and a representation as a value of type 25533@code{Standard.String}, using a specified wide character 25534encoding method. It uses definitions in 25535package @code{System.Wch_Con}. 25536 25537@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 25538@anchor{gnat_rm/the_gnat_library id156}@anchor{407}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{408} 25539@section @code{System.Wch_Con} (@code{s-wchcon.ads}) 25540 25541 25542@geindex System.Wch_Con (s-wchcon.ads) 25543 25544This package provides definitions and descriptions of 25545the various methods used for encoding wide characters 25546in ordinary strings. These definitions are used by 25547the package @code{System.Wch_Cnv}. 25548 25549@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 25550@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{409}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40a} 25551@chapter Interfacing to Other Languages 25552 25553 25554The facilities in Annex B of the Ada Reference Manual are fully 25555implemented in GNAT, and in addition, a full interface to C++ is 25556provided. 25557 25558@menu 25559* Interfacing to C:: 25560* Interfacing to C++:: 25561* Interfacing to COBOL:: 25562* Interfacing to Fortran:: 25563* Interfacing to non-GNAT Ada code:: 25564 25565@end menu 25566 25567@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 25568@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{40b}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{40c} 25569@section Interfacing to C 25570 25571 25572Interfacing to C with GNAT can use one of two approaches: 25573 25574 25575@itemize * 25576 25577@item 25578The types in the package @code{Interfaces.C} may be used. 25579 25580@item 25581Standard Ada types may be used directly. This may be less portable to 25582other compilers, but will work on all GNAT compilers, which guarantee 25583correspondence between the C and Ada types. 25584@end itemize 25585 25586Pragma @code{Convention C} may be applied to Ada types, but mostly has no 25587effect, since this is the default. The following table shows the 25588correspondence between Ada scalar types and the corresponding C types. 25589 25590 25591@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 25592@headitem 25593 25594Ada Type 25595 25596@tab 25597 25598C Type 25599 25600@item 25601 25602@code{Integer} 25603 25604@tab 25605 25606@code{int} 25607 25608@item 25609 25610@code{Short_Integer} 25611 25612@tab 25613 25614@code{short} 25615 25616@item 25617 25618@code{Short_Short_Integer} 25619 25620@tab 25621 25622@code{signed char} 25623 25624@item 25625 25626@code{Long_Integer} 25627 25628@tab 25629 25630@code{long} 25631 25632@item 25633 25634@code{Long_Long_Integer} 25635 25636@tab 25637 25638@code{long long} 25639 25640@item 25641 25642@code{Short_Float} 25643 25644@tab 25645 25646@code{float} 25647 25648@item 25649 25650@code{Float} 25651 25652@tab 25653 25654@code{float} 25655 25656@item 25657 25658@code{Long_Float} 25659 25660@tab 25661 25662@code{double} 25663 25664@item 25665 25666@code{Long_Long_Float} 25667 25668@tab 25669 25670This is the longest floating-point type supported by the hardware. 25671 25672@end multitable 25673 25674 25675Additionally, there are the following general correspondences between Ada 25676and C types: 25677 25678 25679@itemize * 25680 25681@item 25682Ada enumeration types map to C enumeration types directly if pragma 25683@code{Convention C} is specified, which causes them to have a length of 2568432 bits, except for boolean types which map to C99 @code{bool} and for 25685which the length is 8 bits. 25686Without pragma @code{Convention C}, Ada enumeration types map to 256878, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, 25688@code{int}, respectively) depending on the number of values passed. 25689This is the only case in which pragma @code{Convention C} affects the 25690representation of an Ada type. 25691 25692@item 25693Ada access types map to C pointers, except for the case of pointers to 25694unconstrained types in Ada, which have no direct C equivalent. 25695 25696@item 25697Ada arrays map directly to C arrays. 25698 25699@item 25700Ada records map directly to C structures. 25701 25702@item 25703Packed Ada records map to C structures where all members are bit fields 25704of the length corresponding to the @code{type'Size} value in Ada. 25705@end itemize 25706 25707@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 25708@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{40d}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{4a} 25709@section Interfacing to C++ 25710 25711 25712The interface to C++ makes use of the following pragmas, which are 25713primarily intended to be constructed automatically using a binding generator 25714tool, although it is possible to construct them by hand. 25715 25716Using these pragmas it is possible to achieve complete 25717inter-operability between Ada tagged types and C++ class definitions. 25718See @ref{7,,Implementation Defined Pragmas}, for more details. 25719 25720 25721@table @asis 25722 25723@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} 25724 25725The argument denotes an entity in the current declarative region that is 25726declared as a tagged or untagged record type. It indicates that the type 25727corresponds to an externally declared C++ class type, and is to be laid 25728out the same way that C++ would lay out the type. 25729 25730Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 25731for backward compatibility but its functionality is available 25732using pragma @code{Import} with @code{Convention} = @code{CPP}. 25733 25734@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} 25735 25736This pragma identifies an imported function (imported in the usual way 25737with pragma @code{Import}) as corresponding to a C++ constructor. 25738@end table 25739 25740A few restrictions are placed on the use of the @code{Access} attribute 25741in conjunction with subprograms subject to convention @code{CPP}: the 25742attribute may be used neither on primitive operations of a tagged 25743record type with convention @code{CPP}, imported or not, nor on 25744subprograms imported with pragma @code{CPP_Constructor}. 25745 25746In addition, C++ exceptions are propagated and can be handled in an 25747@code{others} choice of an exception handler. The corresponding Ada 25748occurrence has no message, and the simple name of the exception identity 25749contains @code{Foreign_Exception}. Finalization and awaiting dependent 25750tasks works properly when such foreign exceptions are propagated. 25751 25752It is also possible to import a C++ exception using the following syntax: 25753 25754@example 25755LOCAL_NAME : exception; 25756pragma Import (Cpp, 25757 [Entity =>] LOCAL_NAME, 25758 [External_Name =>] static_string_EXPRESSION); 25759@end example 25760 25761The @code{External_Name} is the name of the C++ RTTI symbol. You can then 25762cover a specific C++ exception in an exception handler. 25763 25764@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 25765@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{40e}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{40f} 25766@section Interfacing to COBOL 25767 25768 25769Interfacing to COBOL is achieved as described in section B.4 of 25770the Ada Reference Manual. 25771 25772@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 25773@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{410}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{411} 25774@section Interfacing to Fortran 25775 25776 25777Interfacing to Fortran is achieved as described in section B.5 of the 25778Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 25779multi-dimensional array causes the array to be stored in column-major 25780order as required for convenient interface to Fortran. 25781 25782@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 25783@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{412}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{413} 25784@section Interfacing to non-GNAT Ada code 25785 25786 25787It is possible to specify the convention @code{Ada} in a pragma 25788@code{Import} or pragma @code{Export}. However this refers to 25789the calling conventions used by GNAT, which may or may not be 25790similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 25791compiler to allow interoperation. 25792 25793If arguments types are kept simple, and if the foreign compiler generally 25794follows system calling conventions, then it may be possible to integrate 25795files compiled by other Ada compilers, provided that the elaboration 25796issues are adequately addressed (for example by eliminating the 25797need for any load time elaboration). 25798 25799In particular, GNAT running on VMS is designed to 25800be highly compatible with the DEC Ada 83 compiler, so this is one 25801case in which it is possible to import foreign units of this type, 25802provided that the data items passed are restricted to simple scalar 25803values or simple record types without variants, or simple array 25804types with fixed bounds. 25805 25806@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 25807@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{414}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{415} 25808@chapter Specialized Needs Annexes 25809 25810 25811Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 25812required in all implementations. However, as described in this chapter, 25813GNAT implements all of these annexes: 25814 25815 25816@table @asis 25817 25818@item @emph{Systems Programming (Annex C)} 25819 25820The Systems Programming Annex is fully implemented. 25821 25822@item @emph{Real-Time Systems (Annex D)} 25823 25824The Real-Time Systems Annex is fully implemented. 25825 25826@item @emph{Distributed Systems (Annex E)} 25827 25828Stub generation is fully implemented in the GNAT compiler. In addition, 25829a complete compatible PCS is available as part of the GLADE system, 25830a separate product. When the two 25831products are used in conjunction, this annex is fully implemented. 25832 25833@item @emph{Information Systems (Annex F)} 25834 25835The Information Systems annex is fully implemented. 25836 25837@item @emph{Numerics (Annex G)} 25838 25839The Numerics Annex is fully implemented. 25840 25841@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 25842 25843The Safety and Security Annex (termed the High-Integrity Systems Annex 25844in Ada 2005) is fully implemented. 25845@end table 25846 25847@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 25848@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{416}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{417} 25849@chapter Implementation of Specific Ada Features 25850 25851 25852This chapter describes the GNAT implementation of several Ada language 25853facilities. 25854 25855@menu 25856* Machine Code Insertions:: 25857* GNAT Implementation of Tasking:: 25858* GNAT Implementation of Shared Passive Packages:: 25859* Code Generation for Array Aggregates:: 25860* The Size of Discriminated Records with Default Discriminants:: 25861* Strict Conformance to the Ada Reference Manual:: 25862 25863@end menu 25864 25865@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 25866@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{16c}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{418} 25867@section Machine Code Insertions 25868 25869 25870@geindex Machine Code insertions 25871 25872Package @code{Machine_Code} provides machine code support as described 25873in the Ada Reference Manual in two separate forms: 25874 25875 25876@itemize * 25877 25878@item 25879Machine code statements, consisting of qualified expressions that 25880fit the requirements of RM section 13.8. 25881 25882@item 25883An intrinsic callable procedure, providing an alternative mechanism of 25884including machine instructions in a subprogram. 25885@end itemize 25886 25887The two features are similar, and both are closely related to the mechanism 25888provided by the asm instruction in the GNU C compiler. Full understanding 25889and use of the facilities in this package requires understanding the asm 25890instruction, see the section on Extended Asm in 25891@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 25892 25893Calls to the function @code{Asm} and the procedure @code{Asm} have identical 25894semantic restrictions and effects as described below. Both are provided so 25895that the procedure call can be used as a statement, and the function call 25896can be used to form a code_statement. 25897 25898Consider this C @code{asm} instruction: 25899 25900@example 25901asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 25902@end example 25903 25904The equivalent can be written for GNAT as: 25905 25906@example 25907Asm ("fsinx %1 %0", 25908 My_Float'Asm_Output ("=f", result), 25909 My_Float'Asm_Input ("f", angle)); 25910@end example 25911 25912The first argument to @code{Asm} is the assembler template, and is 25913identical to what is used in GNU C. This string must be a static 25914expression. The second argument is the output operand list. It is 25915either a single @code{Asm_Output} attribute reference, or a list of such 25916references enclosed in parentheses (technically an array aggregate of 25917such references). 25918 25919The @code{Asm_Output} attribute denotes a function that takes two 25920parameters. The first is a string, the second is the name of a variable 25921of the type designated by the attribute prefix. The first (string) 25922argument is required to be a static expression and designates the 25923constraint (see the section on Constraints in 25924@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 25925for the parameter; e.g., what kind of register is required. The second 25926argument is the variable to be written or updated with the 25927result. The possible values for constraint are the same as those used in 25928the RTL, and are dependent on the configuration file used to build the 25929GCC back end. If there are no output operands, then this argument may 25930either be omitted, or explicitly given as @code{No_Output_Operands}. 25931No support is provided for GNU C's symbolic names for output parameters. 25932 25933The second argument of @code{my_float'Asm_Output} functions as 25934though it were an @code{out} parameter, which is a little curious, but 25935all names have the form of expressions, so there is no syntactic 25936irregularity, even though normally functions would not be permitted 25937@code{out} parameters. The third argument is the list of input 25938operands. It is either a single @code{Asm_Input} attribute reference, or 25939a list of such references enclosed in parentheses (technically an array 25940aggregate of such references). 25941 25942The @code{Asm_Input} attribute denotes a function that takes two 25943parameters. The first is a string, the second is an expression of the 25944type designated by the prefix. The first (string) argument is required 25945to be a static expression, and is the constraint for the parameter, 25946(e.g., what kind of register is required). The second argument is the 25947value to be used as the input argument. The possible values for the 25948constraint are the same as those used in the RTL, and are dependent on 25949the configuration file used to built the GCC back end. 25950No support is provided for GNU C's symbolic names for input parameters. 25951 25952If there are no input operands, this argument may either be omitted, or 25953explicitly given as @code{No_Input_Operands}. The fourth argument, not 25954present in the above example, is a list of register names, called the 25955@emph{clobber} argument. This argument, if given, must be a static string 25956expression, and is a space or comma separated list of names of registers 25957that must be considered destroyed as a result of the @code{Asm} call. If 25958this argument is the null string (the default value), then the code 25959generator assumes that no additional registers are destroyed. 25960In addition to registers, the special clobbers @code{memory} and 25961@code{cc} as described in the GNU C docs are both supported. 25962 25963The fifth argument, not present in the above example, called the 25964@emph{volatile} argument, is by default @code{False}. It can be set to 25965the literal value @code{True} to indicate to the code generator that all 25966optimizations with respect to the instruction specified should be 25967suppressed, and in particular an instruction that has outputs 25968will still be generated, even if none of the outputs are 25969used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 25970for the full description. 25971Generally it is strongly advisable to use Volatile for any ASM statement 25972that is missing either input or output operands or to avoid unwanted 25973optimizations. A warning is generated if this advice is not followed. 25974 25975No support is provided for GNU C's @code{asm goto} feature. 25976 25977The @code{Asm} subprograms may be used in two ways. First the procedure 25978forms can be used anywhere a procedure call would be valid, and 25979correspond to what the RM calls 'intrinsic' routines. Such calls can 25980be used to intersperse machine instructions with other Ada statements. 25981Second, the function forms, which return a dummy value of the limited 25982private type @code{Asm_Insn}, can be used in code statements, and indeed 25983this is the only context where such calls are allowed. Code statements 25984appear as aggregates of the form: 25985 25986@example 25987Asm_Insn'(Asm (...)); 25988Asm_Insn'(Asm_Volatile (...)); 25989@end example 25990 25991In accordance with RM rules, such code statements are allowed only 25992within subprograms whose entire body consists of such statements. It is 25993not permissible to intermix such statements with other Ada statements. 25994 25995Typically the form using intrinsic procedure calls is more convenient 25996and more flexible. The code statement form is provided to meet the RM 25997suggestion that such a facility should be made available. The following 25998is the exact syntax of the call to @code{Asm}. As usual, if named notation 25999is used, the arguments may be given in arbitrary order, following the 26000normal rules for use of positional and named arguments: 26001 26002@example 26003ASM_CALL ::= Asm ( 26004 [Template =>] static_string_EXPRESSION 26005 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 26006 [,[Inputs =>] INPUT_OPERAND_LIST ] 26007 [,[Clobber =>] static_string_EXPRESSION ] 26008 [,[Volatile =>] static_boolean_EXPRESSION] ) 26009 26010OUTPUT_OPERAND_LIST ::= 26011 [PREFIX.]No_Output_Operands 26012| OUTPUT_OPERAND_ATTRIBUTE 26013| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 26014 26015OUTPUT_OPERAND_ATTRIBUTE ::= 26016 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 26017 26018INPUT_OPERAND_LIST ::= 26019 [PREFIX.]No_Input_Operands 26020| INPUT_OPERAND_ATTRIBUTE 26021| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 26022 26023INPUT_OPERAND_ATTRIBUTE ::= 26024 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 26025@end example 26026 26027The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 26028are declared in the package @code{Machine_Code} and must be referenced 26029according to normal visibility rules. In particular if there is no 26030@code{use} clause for this package, then appropriate package name 26031qualification is required. 26032 26033@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 26034@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41a} 26035@section GNAT Implementation of Tasking 26036 26037 26038This chapter outlines the basic GNAT approach to tasking (in particular, 26039a multi-layered library for portability) and discusses issues related 26040to compliance with the Real-Time Systems Annex. 26041 26042@menu 26043* Mapping Ada Tasks onto the Underlying Kernel Threads:: 26044* Ensuring Compliance with the Real-Time Annex:: 26045* Support for Locking Policies:: 26046 26047@end menu 26048 26049@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 26050@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{41c} 26051@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 26052 26053 26054GNAT's run-time support comprises two layers: 26055 26056 26057@itemize * 26058 26059@item 26060GNARL (GNAT Run-time Layer) 26061 26062@item 26063GNULL (GNAT Low-level Library) 26064@end itemize 26065 26066In GNAT, Ada's tasking services rely on a platform and OS independent 26067layer known as GNARL. This code is responsible for implementing the 26068correct semantics of Ada's task creation, rendezvous, protected 26069operations etc. 26070 26071GNARL decomposes Ada's tasking semantics into simpler lower level 26072operations such as create a thread, set the priority of a thread, 26073yield, create a lock, lock/unlock, etc. The spec for these low-level 26074operations constitutes GNULLI, the GNULL Interface. This interface is 26075directly inspired from the POSIX real-time API. 26076 26077If the underlying executive or OS implements the POSIX standard 26078faithfully, the GNULL Interface maps as is to the services offered by 26079the underlying kernel. Otherwise, some target dependent glue code maps 26080the services offered by the underlying kernel to the semantics expected 26081by GNARL. 26082 26083Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 26084key point is that each Ada task is mapped on a thread in the underlying 26085kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 26086 26087In addition Ada task priorities map onto the underlying thread priorities. 26088Mapping Ada tasks onto the underlying kernel threads has several advantages: 26089 26090 26091@itemize * 26092 26093@item 26094The underlying scheduler is used to schedule the Ada tasks. This 26095makes Ada tasks as efficient as kernel threads from a scheduling 26096standpoint. 26097 26098@item 26099Interaction with code written in C containing threads is eased 26100since at the lowest level Ada tasks and C threads map onto the same 26101underlying kernel concept. 26102 26103@item 26104When an Ada task is blocked during I/O the remaining Ada tasks are 26105able to proceed. 26106 26107@item 26108On multiprocessor systems Ada tasks can execute in parallel. 26109@end itemize 26110 26111Some threads libraries offer a mechanism to fork a new process, with the 26112child process duplicating the threads from the parent. 26113GNAT does not 26114support this functionality when the parent contains more than one task. 26115 26116@geindex Forking a new process 26117 26118@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 26119@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{41e} 26120@subsection Ensuring Compliance with the Real-Time Annex 26121 26122 26123@geindex Real-Time Systems Annex compliance 26124 26125Although mapping Ada tasks onto 26126the underlying threads has significant advantages, it does create some 26127complications when it comes to respecting the scheduling semantics 26128specified in the real-time annex (Annex D). 26129 26130For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 26131scheduling policy states: 26132 26133@quotation 26134 26135@emph{When the active priority of a ready task that is not running 26136changes, or the setting of its base priority takes effect, the 26137task is removed from the ready queue for its old active priority 26138and is added at the tail of the ready queue for its new active 26139priority, except in the case where the active priority is lowered 26140due to the loss of inherited priority, in which case the task is 26141added at the head of the ready queue for its new active priority.} 26142@end quotation 26143 26144While most kernels do put tasks at the end of the priority queue when 26145a task changes its priority, (which respects the main 26146FIFO_Within_Priorities requirement), almost none keep a thread at the 26147beginning of its priority queue when its priority drops from the loss 26148of inherited priority. 26149 26150As a result most vendors have provided incomplete Annex D implementations. 26151 26152The GNAT run-time, has a nice cooperative solution to this problem 26153which ensures that accurate FIFO_Within_Priorities semantics are 26154respected. 26155 26156The principle is as follows. When an Ada task T is about to start 26157running, it checks whether some other Ada task R with the same 26158priority as T has been suspended due to the loss of priority 26159inheritance. If this is the case, T yields and is placed at the end of 26160its priority queue. When R arrives at the front of the queue it 26161executes. 26162 26163Note that this simple scheme preserves the relative order of the tasks 26164that were ready to execute in the priority queue where R has been 26165placed at the end. 26166 26167@c Support_for_Locking_Policies 26168 26169@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking 26170@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{41f} 26171@subsection Support for Locking Policies 26172 26173 26174This section specifies which policies specified by pragma Locking_Policy 26175are supported on which platforms. 26176 26177GNAT supports the standard @code{Ceiling_Locking} policy, and the 26178implementation defined @code{Inheritance_Locking} and 26179@code{Concurrent_Readers_Locking} policies. 26180 26181@code{Ceiling_Locking} is supported on all platforms if the operating system 26182supports it. In particular, @code{Ceiling_Locking} is not supported on 26183VxWorks. 26184@code{Inheritance_Locking} is supported on 26185Linux, 26186Darwin (Mac OS X), 26187LynxOS 178, 26188and VxWorks. 26189@code{Concurrent_Readers_Locking} is supported on Linux. 26190 26191Notes about @code{Ceiling_Locking} on Linux: 26192If the process is running as 'root', ceiling locking is used. 26193If the capabilities facility is installed 26194("sudo apt-get --assume-yes install libcap-dev" on Ubuntu, 26195for example), 26196and the program is linked against that library 26197("-largs -lcap"), 26198and the executable file has the cap_sys_nice capability 26199("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"), 26200then ceiling locking is used. 26201Otherwise, the @code{Ceiling_Locking} policy is ignored. 26202 26203@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 26204@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{421} 26205@section GNAT Implementation of Shared Passive Packages 26206 26207 26208@geindex Shared passive packages 26209 26210GNAT fully implements the 26211@geindex pragma Shared_Passive 26212pragma 26213@code{Shared_Passive} for 26214the purpose of designating shared passive packages. 26215This allows the use of passive partitions in the 26216context described in the Ada Reference Manual; i.e., for communication 26217between separate partitions of a distributed application using the 26218features in Annex E. 26219 26220@geindex Annex E 26221 26222@geindex Distribution Systems Annex 26223 26224However, the implementation approach used by GNAT provides for more 26225extensive usage as follows: 26226 26227 26228@table @asis 26229 26230@item @emph{Communication between separate programs} 26231 26232This allows separate programs to access the data in passive 26233partitions, using protected objects for synchronization where 26234needed. The only requirement is that the two programs have a 26235common shared file system. It is even possible for programs 26236running on different machines with different architectures 26237(e.g., different endianness) to communicate via the data in 26238a passive partition. 26239 26240@item @emph{Persistence between program runs} 26241 26242The data in a passive package can persist from one run of a 26243program to another, so that a later program sees the final 26244values stored by a previous run of the same program. 26245@end table 26246 26247The implementation approach used is to store the data in files. A 26248separate stream file is created for each object in the package, and 26249an access to an object causes the corresponding file to be read or 26250written. 26251 26252@geindex SHARED_MEMORY_DIRECTORY environment variable 26253 26254The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 26255set to the directory to be used for these files. 26256The files in this directory 26257have names that correspond to their fully qualified names. For 26258example, if we have the package 26259 26260@example 26261package X is 26262 pragma Shared_Passive (X); 26263 Y : Integer; 26264 Z : Float; 26265end X; 26266@end example 26267 26268and the environment variable is set to @code{/stemp/}, then the files created 26269will have the names: 26270 26271@example 26272/stemp/x.y 26273/stemp/x.z 26274@end example 26275 26276These files are created when a value is initially written to the object, and 26277the files are retained until manually deleted. This provides the persistence 26278semantics. If no file exists, it means that no partition has assigned a value 26279to the variable; in this case the initial value declared in the package 26280will be used. This model ensures that there are no issues in synchronizing 26281the elaboration process, since elaboration of passive packages elaborates the 26282initial values, but does not create the files. 26283 26284The files are written using normal @code{Stream_IO} access. 26285If you want to be able 26286to communicate between programs or partitions running on different 26287architectures, then you should use the XDR versions of the stream attribute 26288routines, since these are architecture independent. 26289 26290If active synchronization is required for access to the variables in the 26291shared passive package, then as described in the Ada Reference Manual, the 26292package may contain protected objects used for this purpose. In this case 26293a lock file (whose name is @code{___lock} (three underscores) 26294is created in the shared memory directory. 26295 26296@geindex ___lock file (for shared passive packages) 26297 26298This is used to provide the required locking 26299semantics for proper protected object synchronization. 26300 26301@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 26302@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{423} 26303@section Code Generation for Array Aggregates 26304 26305 26306Aggregates have a rich syntax and allow the user to specify the values of 26307complex data structures by means of a single construct. As a result, the 26308code generated for aggregates can be quite complex and involve loops, case 26309statements and multiple assignments. In the simplest cases, however, the 26310compiler will recognize aggregates whose components and constraints are 26311fully static, and in those cases the compiler will generate little or no 26312executable code. The following is an outline of the code that GNAT generates 26313for various aggregate constructs. For further details, you will find it 26314useful to examine the output produced by the -gnatG flag to see the expanded 26315source that is input to the code generator. You may also want to examine 26316the assembly code generated at various levels of optimization. 26317 26318The code generated for aggregates depends on the context, the component values, 26319and the type. In the context of an object declaration the code generated is 26320generally simpler than in the case of an assignment. As a general rule, static 26321component values and static subtypes also lead to simpler code. 26322 26323@menu 26324* Static constant aggregates with static bounds:: 26325* Constant aggregates with unconstrained nominal types:: 26326* Aggregates with static bounds:: 26327* Aggregates with nonstatic bounds:: 26328* Aggregates in assignment statements:: 26329 26330@end menu 26331 26332@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 26333@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{424}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{425} 26334@subsection Static constant aggregates with static bounds 26335 26336 26337For the declarations: 26338 26339@example 26340type One_Dim is array (1..10) of integer; 26341ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 26342@end example 26343 26344GNAT generates no executable code: the constant ar0 is placed in static memory. 26345The same is true for constant aggregates with named associations: 26346 26347@example 26348Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 26349Cr3 : constant One_Dim := (others => 7777); 26350@end example 26351 26352The same is true for multidimensional constant arrays such as: 26353 26354@example 26355type two_dim is array (1..3, 1..3) of integer; 26356Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 26357@end example 26358 26359The same is true for arrays of one-dimensional arrays: the following are 26360static: 26361 26362@example 26363type ar1b is array (1..3) of boolean; 26364type ar_ar is array (1..3) of ar1b; 26365None : constant ar1b := (others => false); -- fully static 26366None2 : constant ar_ar := (1..3 => None); -- fully static 26367@end example 26368 26369However, for multidimensional aggregates with named associations, GNAT will 26370generate assignments and loops, even if all associations are static. The 26371following two declarations generate a loop for the first dimension, and 26372individual component assignments for the second dimension: 26373 26374@example 26375Zero1: constant two_dim := (1..3 => (1..3 => 0)); 26376Zero2: constant two_dim := (others => (others => 0)); 26377@end example 26378 26379@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 26380@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{426}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{427} 26381@subsection Constant aggregates with unconstrained nominal types 26382 26383 26384In such cases the aggregate itself establishes the subtype, so that 26385associations with @code{others} cannot be used. GNAT determines the 26386bounds for the actual subtype of the aggregate, and allocates the 26387aggregate statically as well. No code is generated for the following: 26388 26389@example 26390type One_Unc is array (natural range <>) of integer; 26391Cr_Unc : constant One_Unc := (12,24,36); 26392@end example 26393 26394@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 26395@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{428}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{429} 26396@subsection Aggregates with static bounds 26397 26398 26399In all previous examples the aggregate was the initial (and immutable) value 26400of a constant. If the aggregate initializes a variable, then code is generated 26401for it as a combination of individual assignments and loops over the target 26402object. The declarations 26403 26404@example 26405Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 26406Cr_Var2 : One_Dim := (others > -1); 26407@end example 26408 26409generate the equivalent of 26410 26411@example 26412Cr_Var1 (1) := 2; 26413Cr_Var1 (2) := 3; 26414Cr_Var1 (3) := 5; 26415Cr_Var1 (4) := 11; 26416 26417for I in Cr_Var2'range loop 26418 Cr_Var2 (I) := -1; 26419end loop; 26420@end example 26421 26422@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 26423@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{42a}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42b} 26424@subsection Aggregates with nonstatic bounds 26425 26426 26427If the bounds of the aggregate are not statically compatible with the bounds 26428of the nominal subtype of the target, then constraint checks have to be 26429generated on the bounds. For a multidimensional array, constraint checks may 26430have to be applied to sub-arrays individually, if they do not have statically 26431compatible subtypes. 26432 26433@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 26434@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{42c}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{42d} 26435@subsection Aggregates in assignment statements 26436 26437 26438In general, aggregate assignment requires the construction of a temporary, 26439and a copy from the temporary to the target of the assignment. This is because 26440it is not always possible to convert the assignment into a series of individual 26441component assignments. For example, consider the simple case: 26442 26443@example 26444A := (A(2), A(1)); 26445@end example 26446 26447This cannot be converted into: 26448 26449@example 26450A(1) := A(2); 26451A(2) := A(1); 26452@end example 26453 26454So the aggregate has to be built first in a separate location, and then 26455copied into the target. GNAT recognizes simple cases where this intermediate 26456step is not required, and the assignments can be performed in place, directly 26457into the target. The following sufficient criteria are applied: 26458 26459 26460@itemize * 26461 26462@item 26463The bounds of the aggregate are static, and the associations are static. 26464 26465@item 26466The components of the aggregate are static constants, names of 26467simple variables that are not renamings, or expressions not involving 26468indexed components whose operands obey these rules. 26469@end itemize 26470 26471If any of these conditions are violated, the aggregate will be built in 26472a temporary (created either by the front-end or the code generator) and then 26473that temporary will be copied onto the target. 26474 26475@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 26476@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{42e}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{42f} 26477@section The Size of Discriminated Records with Default Discriminants 26478 26479 26480If a discriminated type @code{T} has discriminants with default values, it is 26481possible to declare an object of this type without providing an explicit 26482constraint: 26483 26484@example 26485type Size is range 1..100; 26486 26487type Rec (D : Size := 15) is record 26488 Name : String (1..D); 26489end T; 26490 26491Word : Rec; 26492@end example 26493 26494Such an object is said to be @emph{unconstrained}. 26495The discriminant of the object 26496can be modified by a full assignment to the object, as long as it preserves the 26497relation between the value of the discriminant, and the value of the components 26498that depend on it: 26499 26500@example 26501Word := (3, "yes"); 26502 26503Word := (5, "maybe"); 26504 26505Word := (5, "no"); -- raises Constraint_Error 26506@end example 26507 26508In order to support this behavior efficiently, an unconstrained object is 26509given the maximum size that any value of the type requires. In the case 26510above, @code{Word} has storage for the discriminant and for 26511a @code{String} of length 100. 26512It is important to note that unconstrained objects do not require dynamic 26513allocation. It would be an improper implementation to place on the heap those 26514components whose size depends on discriminants. (This improper implementation 26515was used by some Ada83 compilers, where the @code{Name} component above 26516would have 26517been stored as a pointer to a dynamic string). Following the principle that 26518dynamic storage management should never be introduced implicitly, 26519an Ada compiler should reserve the full size for an unconstrained declared 26520object, and place it on the stack. 26521 26522This maximum size approach 26523has been a source of surprise to some users, who expect the default 26524values of the discriminants to determine the size reserved for an 26525unconstrained object: "If the default is 15, why should the object occupy 26526a larger size?" 26527The answer, of course, is that the discriminant may be later modified, 26528and its full range of values must be taken into account. This is why the 26529declaration: 26530 26531@example 26532type Rec (D : Positive := 15) is record 26533 Name : String (1..D); 26534end record; 26535 26536Too_Large : Rec; 26537@end example 26538 26539is flagged by the compiler with a warning: 26540an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 26541because the required size includes @code{Positive'Last} 26542bytes. As the first example indicates, the proper approach is to declare an 26543index type of 'reasonable' range so that unconstrained objects are not too 26544large. 26545 26546One final wrinkle: if the object is declared to be @code{aliased}, or if it is 26547created in the heap by means of an allocator, then it is @emph{not} 26548unconstrained: 26549it is constrained by the default values of the discriminants, and those values 26550cannot be modified by full assignment. This is because in the presence of 26551aliasing all views of the object (which may be manipulated by different tasks, 26552say) must be consistent, so it is imperative that the object, once created, 26553remain invariant. 26554 26555@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features 26556@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{430}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{431} 26557@section Strict Conformance to the Ada Reference Manual 26558 26559 26560The dynamic semantics defined by the Ada Reference Manual impose a set of 26561run-time checks to be generated. By default, the GNAT compiler will insert many 26562run-time checks into the compiled code, including most of those required by the 26563Ada Reference Manual. However, there are two checks that are not enabled in 26564the default mode for efficiency reasons: checks for access before elaboration 26565on subprogram calls, and stack overflow checking (most operating systems do not 26566perform this check by default). 26567 26568Strict conformance to the Ada Reference Manual can be achieved by adding two 26569compiler options for dynamic checks for access-before-elaboration on subprogram 26570calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 26571(@emph{-fstack-check}). 26572 26573Note that the result of a floating point arithmetic operation in overflow and 26574invalid situations, when the @code{Machine_Overflows} attribute of the result 26575type is @code{False}, is to generate IEEE NaN and infinite values. This is the 26576case for machines compliant with the IEEE floating-point standard, but on 26577machines that are not fully compliant with this standard, such as Alpha, the 26578@emph{-mieee} compiler flag must be used for achieving IEEE confirming 26579behavior (although at the cost of a significant performance penalty), so 26580infinite and NaN values are properly generated. 26581 26582@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top 26583@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{432}@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{433} 26584@chapter Implementation of Ada 2012 Features 26585 26586 26587@geindex Ada 2012 implementation status 26588 26589@geindex -gnat12 option (gcc) 26590 26591@geindex pragma Ada_2012 26592 26593@geindex configuration pragma Ada_2012 26594 26595@geindex Ada_2012 configuration pragma 26596 26597This chapter contains a complete list of Ada 2012 features that have been 26598implemented. 26599Generally, these features are only 26600available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 26601which is the default behavior, 26602or if the configuration pragma @code{Ada_2012} is used. 26603 26604However, new pragmas, attributes, and restrictions are 26605unconditionally available, since the Ada 95 standard allows the addition of 26606new pragmas, attributes, and restrictions (there are exceptions, which are 26607documented in the individual descriptions), and also certain packages 26608were made available in earlier versions of Ada. 26609 26610An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 26611This date shows the implementation date of the feature. Any wavefront 26612subsequent to this date will contain the indicated feature, as will any 26613subsequent releases. A date of 0000-00-00 means that GNAT has always 26614implemented the feature, or implemented it as soon as it appeared as a 26615binding interpretation. 26616 26617Each feature corresponds to an Ada Issue ('AI') approved by the Ada 26618standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 26619The features are ordered based on the relevant sections of the Ada 26620Reference Manual ("RM"). When a given AI relates to multiple points 26621in the RM, the earliest is used. 26622 26623A complete description of the AIs may be found in 26624@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 26625 26626@geindex AI-0176 (Ada 2012 feature) 26627 26628 26629@itemize * 26630 26631@item 26632@emph{AI-0176 Quantified expressions (2010-09-29)} 26633 26634Both universally and existentially quantified expressions are implemented. 26635They use the new syntax for iterators proposed in AI05-139-2, as well as 26636the standard Ada loop syntax. 26637 26638RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 26639@end itemize 26640 26641@geindex AI-0079 (Ada 2012 feature) 26642 26643 26644@itemize * 26645 26646@item 26647@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 26648 26649Wide characters in the unicode category @emph{other_format} are now allowed in 26650source programs between tokens, but not within a token such as an identifier. 26651 26652RM References: 2.01 (4/2) 2.02 (7) 26653@end itemize 26654 26655@geindex AI-0091 (Ada 2012 feature) 26656 26657 26658@itemize * 26659 26660@item 26661@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 26662 26663Wide characters in the unicode category @emph{other_format} are not permitted 26664within an identifier, since this can be a security problem. The error 26665message for this case has been improved to be more specific, but GNAT has 26666never allowed such characters to appear in identifiers. 26667 26668RM 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) 26669@end itemize 26670 26671@geindex AI-0100 (Ada 2012 feature) 26672 26673 26674@itemize * 26675 26676@item 26677@emph{AI-0100 Placement of pragmas (2010-07-01)} 26678 26679This AI is an earlier version of AI-163. It simplifies the rules 26680for legal placement of pragmas. In the case of lists that allow pragmas, if 26681the list may have no elements, then the list may consist solely of pragmas. 26682 26683RM References: 2.08 (7) 26684@end itemize 26685 26686@geindex AI-0163 (Ada 2012 feature) 26687 26688 26689@itemize * 26690 26691@item 26692@emph{AI-0163 Pragmas in place of null (2010-07-01)} 26693 26694A statement sequence may be composed entirely of pragmas. It is no longer 26695necessary to add a dummy @code{null} statement to make the sequence legal. 26696 26697RM References: 2.08 (7) 2.08 (16) 26698@end itemize 26699 26700@geindex AI-0080 (Ada 2012 feature) 26701 26702 26703@itemize * 26704 26705@item 26706@emph{AI-0080 'View of' not needed if clear from context (0000-00-00)} 26707 26708This is an editorial change only, described as non-testable in the AI. 26709 26710RM References: 3.01 (7) 26711@end itemize 26712 26713@geindex AI-0183 (Ada 2012 feature) 26714 26715 26716@itemize * 26717 26718@item 26719@emph{AI-0183 Aspect specifications (2010-08-16)} 26720 26721Aspect specifications have been fully implemented except for pre and post- 26722conditions, and type invariants, which have their own separate AI's. All 26723forms of declarations listed in the AI are supported. The following is a 26724list of the aspects supported (with GNAT implementation aspects marked) 26725@end itemize 26726 26727 26728@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 26729@headitem 26730 26731Supported Aspect 26732 26733@tab 26734 26735Source 26736 26737@item 26738 26739@code{Ada_2005} 26740 26741@tab 26742 26743-- GNAT 26744 26745@item 26746 26747@code{Ada_2012} 26748 26749@tab 26750 26751-- GNAT 26752 26753@item 26754 26755@code{Address} 26756 26757@tab 26758 26759@item 26760 26761@code{Alignment} 26762 26763@tab 26764 26765@item 26766 26767@code{Atomic} 26768 26769@tab 26770 26771@item 26772 26773@code{Atomic_Components} 26774 26775@tab 26776 26777@item 26778 26779@code{Bit_Order} 26780 26781@tab 26782 26783@item 26784 26785@code{Component_Size} 26786 26787@tab 26788 26789@item 26790 26791@code{Contract_Cases} 26792 26793@tab 26794 26795-- GNAT 26796 26797@item 26798 26799@code{Discard_Names} 26800 26801@tab 26802 26803@item 26804 26805@code{External_Tag} 26806 26807@tab 26808 26809@item 26810 26811@code{Favor_Top_Level} 26812 26813@tab 26814 26815-- GNAT 26816 26817@item 26818 26819@code{Inline} 26820 26821@tab 26822 26823@item 26824 26825@code{Inline_Always} 26826 26827@tab 26828 26829-- GNAT 26830 26831@item 26832 26833@code{Invariant} 26834 26835@tab 26836 26837-- GNAT 26838 26839@item 26840 26841@code{Machine_Radix} 26842 26843@tab 26844 26845@item 26846 26847@code{No_Return} 26848 26849@tab 26850 26851@item 26852 26853@code{Object_Size} 26854 26855@tab 26856 26857-- GNAT 26858 26859@item 26860 26861@code{Pack} 26862 26863@tab 26864 26865@item 26866 26867@code{Persistent_BSS} 26868 26869@tab 26870 26871-- GNAT 26872 26873@item 26874 26875@code{Post} 26876 26877@tab 26878 26879@item 26880 26881@code{Pre} 26882 26883@tab 26884 26885@item 26886 26887@code{Predicate} 26888 26889@tab 26890 26891@item 26892 26893@code{Preelaborable_Initialization} 26894 26895@tab 26896 26897@item 26898 26899@code{Pure_Function} 26900 26901@tab 26902 26903-- GNAT 26904 26905@item 26906 26907@code{Remote_Access_Type} 26908 26909@tab 26910 26911-- GNAT 26912 26913@item 26914 26915@code{Shared} 26916 26917@tab 26918 26919-- GNAT 26920 26921@item 26922 26923@code{Size} 26924 26925@tab 26926 26927@item 26928 26929@code{Storage_Pool} 26930 26931@tab 26932 26933@item 26934 26935@code{Storage_Size} 26936 26937@tab 26938 26939@item 26940 26941@code{Stream_Size} 26942 26943@tab 26944 26945@item 26946 26947@code{Suppress} 26948 26949@tab 26950 26951@item 26952 26953@code{Suppress_Debug_Info} 26954 26955@tab 26956 26957-- GNAT 26958 26959@item 26960 26961@code{Test_Case} 26962 26963@tab 26964 26965-- GNAT 26966 26967@item 26968 26969@code{Thread_Local_Storage} 26970 26971@tab 26972 26973-- GNAT 26974 26975@item 26976 26977@code{Type_Invariant} 26978 26979@tab 26980 26981@item 26982 26983@code{Unchecked_Union} 26984 26985@tab 26986 26987@item 26988 26989@code{Universal_Aliasing} 26990 26991@tab 26992 26993-- GNAT 26994 26995@item 26996 26997@code{Unmodified} 26998 26999@tab 27000 27001-- GNAT 27002 27003@item 27004 27005@code{Unreferenced} 27006 27007@tab 27008 27009-- GNAT 27010 27011@item 27012 27013@code{Unreferenced_Objects} 27014 27015@tab 27016 27017-- GNAT 27018 27019@item 27020 27021@code{Unsuppress} 27022 27023@tab 27024 27025@item 27026 27027@code{Value_Size} 27028 27029@tab 27030 27031-- GNAT 27032 27033@item 27034 27035@code{Volatile} 27036 27037@tab 27038 27039@item 27040 27041@code{Volatile_Components} 27042 27043@tab 27044 27045@item 27046 27047@code{Warnings} 27048 27049@tab 27050 27051-- GNAT 27052 27053@end multitable 27054 27055 27056@quotation 27057 27058Note that for aspects with an expression, e.g. @code{Size}, the expression is 27059treated like a default expression (visibility is analyzed at the point of 27060occurrence of the aspect, but evaluation of the expression occurs at the 27061freeze point of the entity involved). 27062 27063RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 270643.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 27065(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 270669.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2706712.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2706813.03.01 (0) 27069@end quotation 27070 27071@geindex AI-0128 (Ada 2012 feature) 27072 27073 27074@itemize * 27075 27076@item 27077@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 27078 27079If an equality operator ("=") is declared for a type, then the implicitly 27080declared inequality operator ("/=") is a primitive operation of the type. 27081This is the only reasonable interpretation, and is the one always implemented 27082by GNAT, but the RM was not entirely clear in making this point. 27083 27084RM References: 3.02.03 (6) 6.06 (6) 27085@end itemize 27086 27087@geindex AI-0003 (Ada 2012 feature) 27088 27089 27090@itemize * 27091 27092@item 27093@emph{AI-0003 Qualified expressions as names (2010-07-11)} 27094 27095In Ada 2012, a qualified expression is considered to be syntactically a name, 27096meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 27097useful in disambiguating some cases of overloading. 27098 27099RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 271005.04 (7) 27101@end itemize 27102 27103@geindex AI-0120 (Ada 2012 feature) 27104 27105 27106@itemize * 27107 27108@item 27109@emph{AI-0120 Constant instance of protected object (0000-00-00)} 27110 27111This is an RM editorial change only. The section that lists objects that are 27112constant failed to include the current instance of a protected object 27113within a protected function. This has always been treated as a constant 27114in GNAT. 27115 27116RM References: 3.03 (21) 27117@end itemize 27118 27119@geindex AI-0008 (Ada 2012 feature) 27120 27121 27122@itemize * 27123 27124@item 27125@emph{AI-0008 General access to constrained objects (0000-00-00)} 27126 27127The wording in the RM implied that if you have a general access to a 27128constrained object, it could be used to modify the discriminants. This was 27129obviously not intended. @code{Constraint_Error} should be raised, and GNAT 27130has always done so in this situation. 27131 27132RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 27133@end itemize 27134 27135@geindex AI-0093 (Ada 2012 feature) 27136 27137 27138@itemize * 27139 27140@item 27141@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 27142 27143This is an editorial change only, to make more widespread use of the Ada 2012 27144'immutably limited'. 27145 27146RM References: 3.03 (23.4/3) 27147@end itemize 27148 27149@geindex AI-0096 (Ada 2012 feature) 27150 27151 27152@itemize * 27153 27154@item 27155@emph{AI-0096 Deriving from formal private types (2010-07-20)} 27156 27157In general it is illegal for a type derived from a formal limited type to be 27158nonlimited. This AI makes an exception to this rule: derivation is legal 27159if it appears in the private part of the generic, and the formal type is not 27160tagged. If the type is tagged, the legality check must be applied to the 27161private part of the package. 27162 27163RM References: 3.04 (5.1/2) 6.02 (7) 27164@end itemize 27165 27166@geindex AI-0181 (Ada 2012 feature) 27167 27168 27169@itemize * 27170 27171@item 27172@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 27173 27174From Ada 2005 on, soft hyphen is considered a non-graphic character, which 27175means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 27176@code{Image} and @code{Value} attributes for the character types. Strictly 27177speaking this is an inconsistency with Ada 95, but in practice the use of 27178these attributes is so obscure that it will not cause problems. 27179 27180RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 27181@end itemize 27182 27183@geindex AI-0182 (Ada 2012 feature) 27184 27185 27186@itemize * 27187 27188@item 27189@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} 27190 27191This AI allows @code{Character'Value} to accept the string @code{'?'} where 27192@code{?} is any character including non-graphic control characters. GNAT has 27193always accepted such strings. It also allows strings such as 27194@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 27195permission and raises @code{Constraint_Error}, as is certainly still 27196permitted. 27197 27198RM References: 3.05 (56/2) 27199@end itemize 27200 27201@geindex AI-0214 (Ada 2012 feature) 27202 27203 27204@itemize * 27205 27206@item 27207@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 27208 27209Ada 2012 relaxes the restriction that forbids discriminants of tagged types 27210to have default expressions by allowing them when the type is limited. It 27211is often useful to define a default value for a discriminant even though 27212it can't be changed by assignment. 27213 27214RM References: 3.07 (9.1/2) 3.07.02 (3) 27215@end itemize 27216 27217@geindex AI-0102 (Ada 2012 feature) 27218 27219 27220@itemize * 27221 27222@item 27223@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 27224 27225It is illegal to assign an anonymous access constant to an anonymous access 27226variable. The RM did not have a clear rule to prevent this, but GNAT has 27227always generated an error for this usage. 27228 27229RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 27230@end itemize 27231 27232@geindex AI-0158 (Ada 2012 feature) 27233 27234 27235@itemize * 27236 27237@item 27238@emph{AI-0158 Generalizing membership tests (2010-09-16)} 27239 27240This AI extends the syntax of membership tests to simplify complex conditions 27241that can be expressed as membership in a subset of values of any type. It 27242introduces syntax for a list of expressions that may be used in loop contexts 27243as well. 27244 27245RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 27246@end itemize 27247 27248@geindex AI-0173 (Ada 2012 feature) 27249 27250 27251@itemize * 27252 27253@item 27254@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 27255 27256The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 27257with the tag of an abstract type, and @code{False} otherwise. 27258 27259RM References: 3.09 (7.4/2) 3.09 (12.4/2) 27260@end itemize 27261 27262@geindex AI-0076 (Ada 2012 feature) 27263 27264 27265@itemize * 27266 27267@item 27268@emph{AI-0076 function with controlling result (0000-00-00)} 27269 27270This is an editorial change only. The RM defines calls with controlling 27271results, but uses the term 'function with controlling result' without an 27272explicit definition. 27273 27274RM References: 3.09.02 (2/2) 27275@end itemize 27276 27277@geindex AI-0126 (Ada 2012 feature) 27278 27279 27280@itemize * 27281 27282@item 27283@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 27284 27285This AI clarifies dispatching rules, and simply confirms that dispatching 27286executes the operation of the parent type when there is no explicitly or 27287implicitly declared operation for the descendant type. This has always been 27288the case in all versions of GNAT. 27289 27290RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 27291@end itemize 27292 27293@geindex AI-0097 (Ada 2012 feature) 27294 27295 27296@itemize * 27297 27298@item 27299@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 27300 27301The RM as written implied that in some cases it was possible to create an 27302object of an abstract type, by having an abstract extension inherit a non- 27303abstract constructor from its parent type. This mistake has been corrected 27304in GNAT and in the RM, and this construct is now illegal. 27305 27306RM References: 3.09.03 (4/2) 27307@end itemize 27308 27309@geindex AI-0203 (Ada 2012 feature) 27310 27311 27312@itemize * 27313 27314@item 27315@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 27316 27317A return_subtype_indication cannot denote an abstract subtype. GNAT has never 27318permitted such usage. 27319 27320RM References: 3.09.03 (8/3) 27321@end itemize 27322 27323@geindex AI-0198 (Ada 2012 feature) 27324 27325 27326@itemize * 27327 27328@item 27329@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 27330 27331This AI resolves a conflict between two rules involving inherited abstract 27332operations and predefined operators. If a derived numeric type inherits 27333an abstract operator, it overrides the predefined one. This interpretation 27334was always the one implemented in GNAT. 27335 27336RM References: 3.09.03 (4/3) 27337@end itemize 27338 27339@geindex AI-0073 (Ada 2012 feature) 27340 27341 27342@itemize * 27343 27344@item 27345@emph{AI-0073 Functions returning abstract types (2010-07-10)} 27346 27347This AI covers a number of issues regarding returning abstract types. In 27348particular generic functions cannot have abstract result types or access 27349result types designated an abstract type. There are some other cases which 27350are detailed in the AI. Note that this binding interpretation has not been 27351retrofitted to operate before Ada 2012 mode, since it caused a significant 27352number of regressions. 27353 27354RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 27355@end itemize 27356 27357@geindex AI-0070 (Ada 2012 feature) 27358 27359 27360@itemize * 27361 27362@item 27363@emph{AI-0070 Elaboration of interface types (0000-00-00)} 27364 27365This is an editorial change only, there are no testable consequences short of 27366checking for the absence of generated code for an interface declaration. 27367 27368RM References: 3.09.04 (18/2) 27369@end itemize 27370 27371@geindex AI-0208 (Ada 2012 feature) 27372 27373 27374@itemize * 27375 27376@item 27377@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 27378 27379The wording in the Ada 2005 RM concerning characteristics of incomplete views 27380was incorrect and implied that some programs intended to be legal were now 27381illegal. GNAT had never considered such programs illegal, so it has always 27382implemented the intent of this AI. 27383 27384RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 27385@end itemize 27386 27387@geindex AI-0162 (Ada 2012 feature) 27388 27389 27390@itemize * 27391 27392@item 27393@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 27394 27395Incomplete types are made more useful by allowing them to be completed by 27396private types and private extensions. 27397 27398RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 27399@end itemize 27400 27401@geindex AI-0098 (Ada 2012 feature) 27402 27403 27404@itemize * 27405 27406@item 27407@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 27408 27409An unintentional omission in the RM implied some inconsistent restrictions on 27410the use of anonymous access to subprogram values. These restrictions were not 27411intentional, and have never been enforced by GNAT. 27412 27413RM References: 3.10.01 (6) 3.10.01 (9.2/2) 27414@end itemize 27415 27416@geindex AI-0199 (Ada 2012 feature) 27417 27418 27419@itemize * 27420 27421@item 27422@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 27423 27424A choice list in a record aggregate can include several components of 27425(distinct) anonymous access types as long as they have matching designated 27426subtypes. 27427 27428RM References: 4.03.01 (16) 27429@end itemize 27430 27431@geindex AI-0220 (Ada 2012 feature) 27432 27433 27434@itemize * 27435 27436@item 27437@emph{AI-0220 Needed components for aggregates (0000-00-00)} 27438 27439This AI addresses a wording problem in the RM that appears to permit some 27440complex cases of aggregates with nonstatic discriminants. GNAT has always 27441implemented the intended semantics. 27442 27443RM References: 4.03.01 (17) 27444@end itemize 27445 27446@geindex AI-0147 (Ada 2012 feature) 27447 27448 27449@itemize * 27450 27451@item 27452@emph{AI-0147 Conditional expressions (2009-03-29)} 27453 27454Conditional expressions are permitted. The form of such an expression is: 27455 27456@example 27457(if expr then expr @{elsif expr then expr@} [else expr]) 27458@end example 27459 27460The parentheses can be omitted in contexts where parentheses are present 27461anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 27462clause is omitted, @strong{else} @emph{True} is assumed; 27463thus @code{(if A then B)} is a way to conveniently represent 27464@emph{(A implies B)} in standard logic. 27465 27466RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 274674.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 27468@end itemize 27469 27470@geindex AI-0037 (Ada 2012 feature) 27471 27472 27473@itemize * 27474 27475@item 27476@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 27477 27478This AI confirms that an association of the form @code{Indx => <>} in an 27479array aggregate must raise @code{Constraint_Error} if @code{Indx} 27480is out of range. The RM specified a range check on other associations, but 27481not when the value of the association was defaulted. GNAT has always inserted 27482a constraint check on the index value. 27483 27484RM References: 4.03.03 (29) 27485@end itemize 27486 27487@geindex AI-0123 (Ada 2012 feature) 27488 27489 27490@itemize * 27491 27492@item 27493@emph{AI-0123 Composability of equality (2010-04-13)} 27494 27495Equality of untagged record composes, so that the predefined equality for a 27496composite type that includes a component of some untagged record type 27497@code{R} uses the equality operation of @code{R} (which may be user-defined 27498or predefined). This makes the behavior of untagged records identical to that 27499of tagged types in this respect. 27500 27501This change is an incompatibility with previous versions of Ada, but it 27502corrects a non-uniformity that was often a source of confusion. Analysis of 27503a large number of industrial programs indicates that in those rare cases 27504where a composite type had an untagged record component with a user-defined 27505equality, either there was no use of the composite equality, or else the code 27506expected the same composability as for tagged types, and thus had a bug that 27507would be fixed by this change. 27508 27509RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 275108.05.04 (8) 27511@end itemize 27512 27513@geindex AI-0088 (Ada 2012 feature) 27514 27515 27516@itemize * 27517 27518@item 27519@emph{AI-0088 The value of exponentiation (0000-00-00)} 27520 27521This AI clarifies the equivalence rule given for the dynamic semantics of 27522exponentiation: the value of the operation can be obtained by repeated 27523multiplication, but the operation can be implemented otherwise (for example 27524using the familiar divide-by-two-and-square algorithm, even if this is less 27525accurate), and does not imply repeated reads of a volatile base. 27526 27527RM References: 4.05.06 (11) 27528@end itemize 27529 27530@geindex AI-0188 (Ada 2012 feature) 27531 27532 27533@itemize * 27534 27535@item 27536@emph{AI-0188 Case expressions (2010-01-09)} 27537 27538Case expressions are permitted. This allows use of constructs such as: 27539 27540@example 27541X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 27542@end example 27543 27544RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 27545@end itemize 27546 27547@geindex AI-0104 (Ada 2012 feature) 27548 27549 27550@itemize * 27551 27552@item 27553@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 27554 27555The assignment @code{Ptr := new not null Some_Ptr;} will raise 27556@code{Constraint_Error} because the default value of the allocated object is 27557@strong{null}. This useless construct is illegal in Ada 2012. 27558 27559RM References: 4.08 (2) 27560@end itemize 27561 27562@geindex AI-0157 (Ada 2012 feature) 27563 27564 27565@itemize * 27566 27567@item 27568@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 27569 27570Allocation and Deallocation from an empty storage pool (i.e. allocation or 27571deallocation of a pointer for which a static storage size clause of zero 27572has been given) is now illegal and is detected as such. GNAT 27573previously gave a warning but not an error. 27574 27575RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 27576@end itemize 27577 27578@geindex AI-0179 (Ada 2012 feature) 27579 27580 27581@itemize * 27582 27583@item 27584@emph{AI-0179 Statement not required after label (2010-04-10)} 27585 27586It is not necessary to have a statement following a label, so a label 27587can appear at the end of a statement sequence without the need for putting a 27588null statement afterwards, but it is not allowable to have only labels and 27589no real statements in a statement sequence. 27590 27591RM References: 5.01 (2) 27592@end itemize 27593 27594@geindex AI-0139-2 (Ada 2012 feature) 27595 27596 27597@itemize * 27598 27599@item 27600@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 27601 27602The new syntax for iterating over arrays and containers is now implemented. 27603Iteration over containers is for now limited to read-only iterators. Only 27604default iterators are supported, with the syntax: @code{for Elem of C}. 27605 27606RM References: 5.05 27607@end itemize 27608 27609@geindex AI-0134 (Ada 2012 feature) 27610 27611 27612@itemize * 27613 27614@item 27615@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 27616 27617For full conformance, the profiles of anonymous-access-to-subprogram 27618parameters must match. GNAT has always enforced this rule. 27619 27620RM References: 6.03.01 (18) 27621@end itemize 27622 27623@geindex AI-0207 (Ada 2012 feature) 27624 27625 27626@itemize * 27627 27628@item 27629@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 27630 27631This AI confirms that access_to_constant indication must match for mode 27632conformance. This was implemented in GNAT when the qualifier was originally 27633introduced in Ada 2005. 27634 27635RM References: 6.03.01 (16/2) 27636@end itemize 27637 27638@geindex AI-0046 (Ada 2012 feature) 27639 27640 27641@itemize * 27642 27643@item 27644@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 27645 27646For full conformance, in the case of access parameters, the null exclusion 27647must match (either both or neither must have @code{not null}). 27648 27649RM References: 6.03.02 (18) 27650@end itemize 27651 27652@geindex AI-0118 (Ada 2012 feature) 27653 27654 27655@itemize * 27656 27657@item 27658@emph{AI-0118 The association of parameter associations (0000-00-00)} 27659 27660This AI clarifies the rules for named associations in subprogram calls and 27661generic instantiations. The rules have been in place since Ada 83. 27662 27663RM References: 6.04.01 (2) 12.03 (9) 27664@end itemize 27665 27666@geindex AI-0196 (Ada 2012 feature) 27667 27668 27669@itemize * 27670 27671@item 27672@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 27673 27674Null exclusion checks are not made for @code{out} parameters when 27675evaluating the actual parameters. GNAT has never generated these checks. 27676 27677RM References: 6.04.01 (13) 27678@end itemize 27679 27680@geindex AI-0015 (Ada 2012 feature) 27681 27682 27683@itemize * 27684 27685@item 27686@emph{AI-0015 Constant return objects (0000-00-00)} 27687 27688The return object declared in an @emph{extended_return_statement} may be 27689declared constant. This was always intended, and GNAT has always allowed it. 27690 27691RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 276926.05 (5.7/2) 27693@end itemize 27694 27695@geindex AI-0032 (Ada 2012 feature) 27696 27697 27698@itemize * 27699 27700@item 27701@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 27702 27703If a function returns a class-wide type, the object of an extended return 27704statement can be declared with a specific type that is covered by the class- 27705wide type. This has been implemented in GNAT since the introduction of 27706extended returns. Note AI-0103 complements this AI by imposing matching 27707rules for constrained return types. 27708 27709RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 277106.05 (8/2) 27711@end itemize 27712 27713@geindex AI-0103 (Ada 2012 feature) 27714 27715 27716@itemize * 27717 27718@item 27719@emph{AI-0103 Static matching for extended return (2010-07-23)} 27720 27721If the return subtype of a function is an elementary type or a constrained 27722type, the subtype indication in an extended return statement must match 27723statically this return subtype. 27724 27725RM References: 6.05 (5.2/2) 27726@end itemize 27727 27728@geindex AI-0058 (Ada 2012 feature) 27729 27730 27731@itemize * 27732 27733@item 27734@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 27735 27736The RM had some incorrect wording implying wrong treatment of abnormal 27737completion in an extended return. GNAT has always implemented the intended 27738correct semantics as described by this AI. 27739 27740RM References: 6.05 (22/2) 27741@end itemize 27742 27743@geindex AI-0050 (Ada 2012 feature) 27744 27745 27746@itemize * 27747 27748@item 27749@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 27750 27751The implementation permissions for raising @code{Constraint_Error} early on a function call 27752when it was clear an exception would be raised were over-permissive and allowed 27753mishandling of discriminants in some cases. GNAT did 27754not take advantage of these incorrect permissions in any case. 27755 27756RM References: 6.05 (24/2) 27757@end itemize 27758 27759@geindex AI-0125 (Ada 2012 feature) 27760 27761 27762@itemize * 27763 27764@item 27765@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 27766 27767In Ada 2012, the declaration of a primitive operation of a type extension 27768or private extension can also override an inherited primitive that is not 27769visible at the point of this declaration. 27770 27771RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 27772@end itemize 27773 27774@geindex AI-0062 (Ada 2012 feature) 27775 27776 27777@itemize * 27778 27779@item 27780@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 27781 27782A full constant may have a null exclusion even if its associated deferred 27783constant does not. GNAT has always allowed this. 27784 27785RM References: 7.04 (6/2) 7.04 (7.1/2) 27786@end itemize 27787 27788@geindex AI-0178 (Ada 2012 feature) 27789 27790 27791@itemize * 27792 27793@item 27794@emph{AI-0178 Incomplete views are limited (0000-00-00)} 27795 27796This AI clarifies the role of incomplete views and plugs an omission in the 27797RM. GNAT always correctly restricted the use of incomplete views and types. 27798 27799RM References: 7.05 (3/2) 7.05 (6/2) 27800@end itemize 27801 27802@geindex AI-0087 (Ada 2012 feature) 27803 27804 27805@itemize * 27806 27807@item 27808@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 27809 27810The actual for a formal nonlimited derived type cannot be limited. In 27811particular, a formal derived type that extends a limited interface but which 27812is not explicitly limited cannot be instantiated with a limited type. 27813 27814RM References: 7.05 (5/2) 12.05.01 (5.1/2) 27815@end itemize 27816 27817@geindex AI-0099 (Ada 2012 feature) 27818 27819 27820@itemize * 27821 27822@item 27823@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 27824 27825This AI clarifies that 'needs finalization' is part of dynamic semantics, 27826and therefore depends on the run-time characteristics of an object (i.e. its 27827tag) and not on its nominal type. As the AI indicates: "we do not expect 27828this to affect any implementation'@w{'}. 27829 27830RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 27831@end itemize 27832 27833@geindex AI-0064 (Ada 2012 feature) 27834 27835 27836@itemize * 27837 27838@item 27839@emph{AI-0064 Redundant finalization rule (0000-00-00)} 27840 27841This is an editorial change only. The intended behavior is already checked 27842by an existing ACATS test, which GNAT has always executed correctly. 27843 27844RM References: 7.06.01 (17.1/1) 27845@end itemize 27846 27847@geindex AI-0026 (Ada 2012 feature) 27848 27849 27850@itemize * 27851 27852@item 27853@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 27854 27855Record representation clauses concerning Unchecked_Union types cannot mention 27856the discriminant of the type. The type of a component declared in the variant 27857part of an Unchecked_Union cannot be controlled, have controlled components, 27858nor have protected or task parts. If an Unchecked_Union type is declared 27859within the body of a generic unit or its descendants, then the type of a 27860component declared in the variant part cannot be a formal private type or a 27861formal private extension declared within the same generic unit. 27862 27863RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 27864@end itemize 27865 27866@geindex AI-0205 (Ada 2012 feature) 27867 27868 27869@itemize * 27870 27871@item 27872@emph{AI-0205 Extended return declares visible name (0000-00-00)} 27873 27874This AI corrects a simple omission in the RM. Return objects have always 27875been visible within an extended return statement. 27876 27877RM References: 8.03 (17) 27878@end itemize 27879 27880@geindex AI-0042 (Ada 2012 feature) 27881 27882 27883@itemize * 27884 27885@item 27886@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 27887 27888This AI fixes a wording gap in the RM. An operation of a synchronized 27889interface can be implemented by a protected or task entry, but the abstract 27890operation is not being overridden in the usual sense, and it must be stated 27891separately that this implementation is legal. This has always been the case 27892in GNAT. 27893 27894RM References: 9.01 (9.2/2) 9.04 (11.1/2) 27895@end itemize 27896 27897@geindex AI-0030 (Ada 2012 feature) 27898 27899 27900@itemize * 27901 27902@item 27903@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 27904 27905Requeue is permitted to a protected, synchronized or task interface primitive 27906providing it is known that the overriding operation is an entry. Otherwise 27907the requeue statement has the same effect as a procedure call. Use of pragma 27908@code{Implemented} provides a way to impose a static requirement on the 27909overriding operation by adhering to one of the implementation kinds: entry, 27910protected procedure or any of the above. 27911 27912RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 279139.05.04 (6) 9.05.04 (7) 9.05.04 (12) 27914@end itemize 27915 27916@geindex AI-0201 (Ada 2012 feature) 27917 27918 27919@itemize * 27920 27921@item 27922@emph{AI-0201 Independence of atomic object components (2010-07-22)} 27923 27924If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 27925attribute, then individual components may not be addressable by independent 27926tasks. However, if the representation clause has no effect (is confirming), 27927then independence is not compromised. Furthermore, in GNAT, specification of 27928other appropriately addressable component sizes (e.g. 16 for 8-bit 27929characters) also preserves independence. GNAT now gives very clear warnings 27930both for the declaration of such a type, and for any assignment to its components. 27931 27932RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 27933@end itemize 27934 27935@geindex AI-0009 (Ada 2012 feature) 27936 27937 27938@itemize * 27939 27940@item 27941@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 27942 27943This AI introduces the new pragmas @code{Independent} and 27944@code{Independent_Components}, 27945which control guaranteeing independence of access to objects and components. 27946The AI also requires independence not unaffected by confirming rep clauses. 27947 27948RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 27949C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 27950@end itemize 27951 27952@geindex AI-0072 (Ada 2012 feature) 27953 27954 27955@itemize * 27956 27957@item 27958@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 27959 27960This AI clarifies that task signalling for reading @code{'Terminated} only 27961occurs if the result is True. GNAT semantics has always been consistent with 27962this notion of task signalling. 27963 27964RM References: 9.10 (6.1/1) 27965@end itemize 27966 27967@geindex AI-0108 (Ada 2012 feature) 27968 27969 27970@itemize * 27971 27972@item 27973@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 27974 27975This AI confirms that an incomplete type from a limited view does not have 27976discriminants. This has always been the case in GNAT. 27977 27978RM References: 10.01.01 (12.3/2) 27979@end itemize 27980 27981@geindex AI-0129 (Ada 2012 feature) 27982 27983 27984@itemize * 27985 27986@item 27987@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 27988 27989This AI clarifies the description of limited views: a limited view of a 27990package includes only one view of a type that has an incomplete declaration 27991and a full declaration (there is no possible ambiguity in a client package). 27992This AI also fixes an omission: a nested package in the private part has no 27993limited view. GNAT always implemented this correctly. 27994 27995RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 27996@end itemize 27997 27998@geindex AI-0077 (Ada 2012 feature) 27999 28000 28001@itemize * 28002 28003@item 28004@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 28005 28006This AI clarifies that a declaration does not include a context clause, 28007and confirms that it is illegal to have a context in which both a limited 28008and a nonlimited view of a package are accessible. Such double visibility 28009was always rejected by GNAT. 28010 28011RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 28012@end itemize 28013 28014@geindex AI-0122 (Ada 2012 feature) 28015 28016 28017@itemize * 28018 28019@item 28020@emph{AI-0122 Private with and children of generics (0000-00-00)} 28021 28022This AI clarifies the visibility of private children of generic units within 28023instantiations of a parent. GNAT has always handled this correctly. 28024 28025RM References: 10.01.02 (12/2) 28026@end itemize 28027 28028@geindex AI-0040 (Ada 2012 feature) 28029 28030 28031@itemize * 28032 28033@item 28034@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 28035 28036This AI confirms that a limited with clause in a child unit cannot name 28037an ancestor of the unit. This has always been checked in GNAT. 28038 28039RM References: 10.01.02 (20/2) 28040@end itemize 28041 28042@geindex AI-0132 (Ada 2012 feature) 28043 28044 28045@itemize * 28046 28047@item 28048@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 28049 28050This AI fills a gap in the description of library unit pragmas. The pragma 28051clearly must apply to a library unit, even if it does not carry the name 28052of the enclosing unit. GNAT has always enforced the required check. 28053 28054RM References: 10.01.05 (7) 28055@end itemize 28056 28057@geindex AI-0034 (Ada 2012 feature) 28058 28059 28060@itemize * 28061 28062@item 28063@emph{AI-0034 Categorization of limited views (0000-00-00)} 28064 28065The RM makes certain limited with clauses illegal because of categorization 28066considerations, when the corresponding normal with would be legal. This is 28067not intended, and GNAT has always implemented the recommended behavior. 28068 28069RM References: 10.02.01 (11/1) 10.02.01 (17/2) 28070@end itemize 28071 28072@geindex AI-0035 (Ada 2012 feature) 28073 28074 28075@itemize * 28076 28077@item 28078@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 28079 28080This AI remedies some inconsistencies in the legality rules for Pure units. 28081Derived access types are legal in a pure unit (on the assumption that the 28082rule for a zero storage pool size has been enforced on the ancestor type). 28083The rules are enforced in generic instances and in subunits. GNAT has always 28084implemented the recommended behavior. 28085 28086RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 28087@end itemize 28088 28089@geindex AI-0219 (Ada 2012 feature) 28090 28091 28092@itemize * 28093 28094@item 28095@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 28096 28097This AI refines the rules for the cases with limited parameters which do not 28098allow the implementations to omit 'redundant'. GNAT now properly conforms 28099to the requirements of this binding interpretation. 28100 28101RM References: 10.02.01 (18/2) 28102@end itemize 28103 28104@geindex AI-0043 (Ada 2012 feature) 28105 28106 28107@itemize * 28108 28109@item 28110@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 28111 28112This AI covers various omissions in the RM regarding the raising of 28113exceptions. GNAT has always implemented the intended semantics. 28114 28115RM References: 11.04.01 (10.1/2) 11 (2) 28116@end itemize 28117 28118@geindex AI-0200 (Ada 2012 feature) 28119 28120 28121@itemize * 28122 28123@item 28124@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 28125 28126This AI plugs a gap in the RM which appeared to allow some obviously intended 28127illegal instantiations. GNAT has never allowed these instantiations. 28128 28129RM References: 12.07 (16) 28130@end itemize 28131 28132@geindex AI-0112 (Ada 2012 feature) 28133 28134 28135@itemize * 28136 28137@item 28138@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 28139 28140This AI concerns giving names to various representation aspects, but the 28141practical effect is simply to make the use of duplicate 28142@code{Atomic[_Components]}, 28143@code{Volatile[_Components]}, and 28144@code{Independent[_Components]} pragmas illegal, and GNAT 28145now performs this required check. 28146 28147RM References: 13.01 (8) 28148@end itemize 28149 28150@geindex AI-0106 (Ada 2012 feature) 28151 28152 28153@itemize * 28154 28155@item 28156@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 28157 28158The RM appeared to allow representation pragmas on generic formal parameters, 28159but this was not intended, and GNAT has never permitted this usage. 28160 28161RM References: 13.01 (9.1/1) 28162@end itemize 28163 28164@geindex AI-0012 (Ada 2012 feature) 28165 28166 28167@itemize * 28168 28169@item 28170@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 28171 28172It is now illegal to give an inappropriate component size or a pragma 28173@code{Pack} that attempts to change the component size in the case of atomic 28174or aliased components. Previously GNAT ignored such an attempt with a 28175warning. 28176 28177RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 28178@end itemize 28179 28180@geindex AI-0039 (Ada 2012 feature) 28181 28182 28183@itemize * 28184 28185@item 28186@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 28187 28188The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 28189for stream attributes, but these were never useful and are now illegal. GNAT 28190has always regarded such expressions as illegal. 28191 28192RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 28193@end itemize 28194 28195@geindex AI-0095 (Ada 2012 feature) 28196 28197 28198@itemize * 28199 28200@item 28201@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 28202 28203The prefix of @code{'Address} cannot statically denote a subprogram with 28204convention @code{Intrinsic}. The use of the @code{Address} attribute raises 28205@code{Program_Error} if the prefix denotes a subprogram with convention 28206@code{Intrinsic}. 28207 28208RM References: 13.03 (11/1) 28209@end itemize 28210 28211@geindex AI-0116 (Ada 2012 feature) 28212 28213 28214@itemize * 28215 28216@item 28217@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 28218 28219This AI requires that the alignment of a class-wide object be no greater 28220than the alignment of any type in the class. GNAT has always followed this 28221recommendation. 28222 28223RM References: 13.03 (29) 13.11 (16) 28224@end itemize 28225 28226@geindex AI-0146 (Ada 2012 feature) 28227 28228 28229@itemize * 28230 28231@item 28232@emph{AI-0146 Type invariants (2009-09-21)} 28233 28234Type invariants may be specified for private types using the aspect notation. 28235Aspect @code{Type_Invariant} may be specified for any private type, 28236@code{Type_Invariant'Class} can 28237only be specified for tagged types, and is inherited by any descendent of the 28238tagged types. The invariant is a boolean expression that is tested for being 28239true in the following situations: conversions to the private type, object 28240declarations for the private type that are default initialized, and 28241[@strong{in}] @strong{out} 28242parameters and returned result on return from any primitive operation for 28243the type that is visible to a client. 28244GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 28245@code{Invariant'Class} for @code{Type_Invariant'Class}. 28246 28247RM References: 13.03.03 (00) 28248@end itemize 28249 28250@geindex AI-0078 (Ada 2012 feature) 28251 28252 28253@itemize * 28254 28255@item 28256@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 28257 28258In Ada 2012, compilers are required to support unchecked conversion where the 28259target alignment is a multiple of the source alignment. GNAT always supported 28260this case (and indeed all cases of differing alignments, doing copies where 28261required if the alignment was reduced). 28262 28263RM References: 13.09 (7) 28264@end itemize 28265 28266@geindex AI-0195 (Ada 2012 feature) 28267 28268 28269@itemize * 28270 28271@item 28272@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 28273 28274The handling of invalid values is now designated to be implementation 28275defined. This is a documentation change only, requiring Annex M in the GNAT 28276Reference Manual to document this handling. 28277In GNAT, checks for invalid values are made 28278only when necessary to avoid erroneous behavior. Operations like assignments 28279which cannot cause erroneous behavior ignore the possibility of invalid 28280values and do not do a check. The date given above applies only to the 28281documentation change, this behavior has always been implemented by GNAT. 28282 28283RM References: 13.09.01 (10) 28284@end itemize 28285 28286@geindex AI-0193 (Ada 2012 feature) 28287 28288 28289@itemize * 28290 28291@item 28292@emph{AI-0193 Alignment of allocators (2010-09-16)} 28293 28294This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 28295analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 28296of size. 28297 28298RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2829913.11.01 (2) 13.11.01 (3) 28300@end itemize 28301 28302@geindex AI-0177 (Ada 2012 feature) 28303 28304 28305@itemize * 28306 28307@item 28308@emph{AI-0177 Parameterized expressions (2010-07-10)} 28309 28310The new Ada 2012 notion of parameterized expressions is implemented. The form 28311is: 28312 28313@example 28314function-specification is (expression) 28315@end example 28316 28317This is exactly equivalent to the 28318corresponding function body that returns the expression, but it can appear 28319in a package spec. Note that the expression must be parenthesized. 28320 28321RM References: 13.11.01 (3/2) 28322@end itemize 28323 28324@geindex AI-0033 (Ada 2012 feature) 28325 28326 28327@itemize * 28328 28329@item 28330@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 28331 28332Neither of these two pragmas may appear within a generic template, because 28333the generic might be instantiated at other than the library level. 28334 28335RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 28336@end itemize 28337 28338@geindex AI-0161 (Ada 2012 feature) 28339 28340 28341@itemize * 28342 28343@item 28344@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 28345 28346A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 28347of the default stream attributes for elementary types. If this restriction is 28348in force, then it is necessary to provide explicit subprograms for any 28349stream attributes used. 28350 28351RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 28352@end itemize 28353 28354@geindex AI-0194 (Ada 2012 feature) 28355 28356 28357@itemize * 28358 28359@item 28360@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 28361 28362The @code{Stream_Size} attribute returns the default number of bits in the 28363stream representation of the given type. 28364This value is not affected by the presence 28365of stream subprogram attributes for the type. GNAT has always implemented 28366this interpretation. 28367 28368RM References: 13.13.02 (1.2/2) 28369@end itemize 28370 28371@geindex AI-0109 (Ada 2012 feature) 28372 28373 28374@itemize * 28375 28376@item 28377@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 28378 28379This AI is an editorial change only. It removes the need for a tag check 28380that can never fail. 28381 28382RM References: 13.13.02 (34/2) 28383@end itemize 28384 28385@geindex AI-0007 (Ada 2012 feature) 28386 28387 28388@itemize * 28389 28390@item 28391@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 28392 28393The RM as written appeared to limit the possibilities of declaring read 28394attribute procedures for private scalar types. This limitation was not 28395intended, and has never been enforced by GNAT. 28396 28397RM References: 13.13.02 (50/2) 13.13.02 (51/2) 28398@end itemize 28399 28400@geindex AI-0065 (Ada 2012 feature) 28401 28402 28403@itemize * 28404 28405@item 28406@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 28407 28408This AI clarifies the fact that all remote access types support external 28409streaming. This fixes an obvious oversight in the definition of the 28410language, and GNAT always implemented the intended correct rules. 28411 28412RM References: 13.13.02 (52/2) 28413@end itemize 28414 28415@geindex AI-0019 (Ada 2012 feature) 28416 28417 28418@itemize * 28419 28420@item 28421@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 28422 28423The RM suggests that primitive subprograms of a specific tagged type are 28424frozen when the tagged type is frozen. This would be an incompatible change 28425and is not intended. GNAT has never attempted this kind of freezing and its 28426behavior is consistent with the recommendation of this AI. 28427 28428RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 28429@end itemize 28430 28431@geindex AI-0017 (Ada 2012 feature) 28432 28433 28434@itemize * 28435 28436@item 28437@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 28438 28439So-called 'Taft-amendment types' (i.e., types that are completed in package 28440bodies) are not frozen by the occurrence of bodies in the 28441enclosing declarative part. GNAT always implemented this properly. 28442 28443RM References: 13.14 (3/1) 28444@end itemize 28445 28446@geindex AI-0060 (Ada 2012 feature) 28447 28448 28449@itemize * 28450 28451@item 28452@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 28453 28454This AI extends the definition of remote access types to include access 28455to limited, synchronized, protected or task class-wide interface types. 28456GNAT already implemented this extension. 28457 28458RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 28459@end itemize 28460 28461@geindex AI-0114 (Ada 2012 feature) 28462 28463 28464@itemize * 28465 28466@item 28467@emph{AI-0114 Classification of letters (0000-00-00)} 28468 28469The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 28470181 (@code{MICRO SIGN}), and 28471186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 28472lower case letters by Unicode. 28473However, they are not allowed in identifiers, and they 28474return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 28475This behavior is consistent with that defined in Ada 95. 28476 28477RM References: A.03.02 (59) A.04.06 (7) 28478@end itemize 28479 28480@geindex AI-0185 (Ada 2012 feature) 28481 28482 28483@itemize * 28484 28485@item 28486@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 28487 28488Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 28489classification functions for @code{Wide_Character} and 28490@code{Wide_Wide_Character}, as well as providing 28491case folding routines for @code{Wide_[Wide_]Character} and 28492@code{Wide_[Wide_]String}. 28493 28494RM References: A.03.05 (0) A.03.06 (0) 28495@end itemize 28496 28497@geindex AI-0031 (Ada 2012 feature) 28498 28499 28500@itemize * 28501 28502@item 28503@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 28504 28505A new version of @code{Find_Token} is added to all relevant string packages, 28506with an extra parameter @code{From}. Instead of starting at the first 28507character of the string, the search for a matching Token starts at the 28508character indexed by the value of @code{From}. 28509These procedures are available in all versions of Ada 28510but if used in versions earlier than Ada 2012 they will generate a warning 28511that an Ada 2012 subprogram is being used. 28512 28513RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 28514A.04.05 (46) 28515@end itemize 28516 28517@geindex AI-0056 (Ada 2012 feature) 28518 28519 28520@itemize * 28521 28522@item 28523@emph{AI-0056 Index on null string returns zero (0000-00-00)} 28524 28525The wording in the Ada 2005 RM implied an incompatible handling of the 28526@code{Index} functions, resulting in raising an exception instead of 28527returning zero in some situations. 28528This was not intended and has been corrected. 28529GNAT always returned zero, and is thus consistent with this AI. 28530 28531RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 28532@end itemize 28533 28534@geindex AI-0137 (Ada 2012 feature) 28535 28536 28537@itemize * 28538 28539@item 28540@emph{AI-0137 String encoding package (2010-03-25)} 28541 28542The packages @code{Ada.Strings.UTF_Encoding}, together with its child 28543packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 28544and @code{Wide_Wide_Strings} have been 28545implemented. These packages (whose documentation can be found in the spec 28546files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 28547@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 28548@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 28549values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 28550UTF-16), as well as conversions between the different UTF encodings. With 28551the exception of @code{Wide_Wide_Strings}, these packages are available in 28552Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 28553The @code{Wide_Wide_Strings} package 28554is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 28555mode since it uses @code{Wide_Wide_Character}). 28556 28557RM References: A.04.11 28558@end itemize 28559 28560@geindex AI-0038 (Ada 2012 feature) 28561 28562 28563@itemize * 28564 28565@item 28566@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 28567 28568These are minor errors in the description on three points. The intent on 28569all these points has always been clear, and GNAT has always implemented the 28570correct intended semantics. 28571 28572RM 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) 28573@end itemize 28574 28575@geindex AI-0044 (Ada 2012 feature) 28576 28577 28578@itemize * 28579 28580@item 28581@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 28582 28583This AI places restrictions on allowed instantiations of generic containers. 28584These restrictions are not checked by the compiler, so there is nothing to 28585change in the implementation. This affects only the RM documentation. 28586 28587RM 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) 28588@end itemize 28589 28590@geindex AI-0127 (Ada 2012 feature) 28591 28592 28593@itemize * 28594 28595@item 28596@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 28597 28598This package provides an interface for identifying the current locale. 28599 28600RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 28601A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 28602@end itemize 28603 28604@geindex AI-0002 (Ada 2012 feature) 28605 28606 28607@itemize * 28608 28609@item 28610@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 28611 28612The compiler is not required to support exporting an Ada subprogram with 28613convention C if there are parameters or a return type of an unconstrained 28614array type (such as @code{String}). GNAT allows such declarations but 28615generates warnings. It is possible, but complicated, to write the 28616corresponding C code and certainly such code would be specific to GNAT and 28617non-portable. 28618 28619RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 28620@end itemize 28621 28622@geindex AI05-0216 (Ada 2012 feature) 28623 28624 28625@itemize * 28626 28627@item 28628@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 28629 28630It is clearly the intention that @code{No_Task_Hierarchy} is intended to 28631forbid tasks declared locally within subprograms, or functions returning task 28632objects, and that is the implementation that GNAT has always provided. 28633However the language in the RM was not sufficiently clear on this point. 28634Thus this is a documentation change in the RM only. 28635 28636RM References: D.07 (3/3) 28637@end itemize 28638 28639@geindex AI-0211 (Ada 2012 feature) 28640 28641 28642@itemize * 28643 28644@item 28645@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 28646 28647The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 28648@code{Ada.Real_Time.Timing_Events.Set_Handler}. 28649 28650RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 28651@end itemize 28652 28653@geindex AI-0190 (Ada 2012 feature) 28654 28655 28656@itemize * 28657 28658@item 28659@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 28660 28661This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 28662used to control storage pools globally. 28663In particular, you can force every access 28664type that is used for allocation (@strong{new}) to have an explicit storage pool, 28665or you can declare a pool globally to be used for all access types that lack 28666an explicit one. 28667 28668RM References: D.07 (8) 28669@end itemize 28670 28671@geindex AI-0189 (Ada 2012 feature) 28672 28673 28674@itemize * 28675 28676@item 28677@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 28678 28679This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 28680which says that no dynamic allocation will occur once elaboration is 28681completed. 28682In general this requires a run-time check, which is not required, and which 28683GNAT does not attempt. But the static cases of allocators in a task body or 28684in the body of the main program are detected and flagged at compile or bind 28685time. 28686 28687RM References: D.07 (19.1/2) H.04 (23.3/2) 28688@end itemize 28689 28690@geindex AI-0171 (Ada 2012 feature) 28691 28692 28693@itemize * 28694 28695@item 28696@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 28697 28698A new package @code{System.Multiprocessors} is added, together with the 28699definition of pragma @code{CPU} for controlling task affinity. A new no 28700dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 28701is added to the Ravenscar profile. 28702 28703RM References: D.13.01 (4/2) D.16 28704@end itemize 28705 28706@geindex AI-0210 (Ada 2012 feature) 28707 28708 28709@itemize * 28710 28711@item 28712@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 28713 28714This is a documentation only issue regarding wording of metric requirements, 28715that does not affect the implementation of the compiler. 28716 28717RM References: D.15 (24/2) 28718@end itemize 28719 28720@geindex AI-0206 (Ada 2012 feature) 28721 28722 28723@itemize * 28724 28725@item 28726@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 28727 28728Remote types packages are now allowed to depend on preelaborated packages. 28729This was formerly considered illegal. 28730 28731RM References: E.02.02 (6) 28732@end itemize 28733 28734@geindex AI-0152 (Ada 2012 feature) 28735 28736 28737@itemize * 28738 28739@item 28740@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 28741 28742Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 28743where the type of the returned value is an anonymous access type. 28744 28745RM References: H.04 (8/1) 28746@end itemize 28747 28748@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top 28749@anchor{gnat_rm/obsolescent_features id1}@anchor{434}@anchor{gnat_rm/obsolescent_features doc}@anchor{435}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15} 28750@chapter Obsolescent Features 28751 28752 28753This chapter describes features that are provided by GNAT, but are 28754considered obsolescent since there are preferred ways of achieving 28755the same effect. These features are provided solely for historical 28756compatibility purposes. 28757 28758@menu 28759* pragma No_Run_Time:: 28760* pragma Ravenscar:: 28761* pragma Restricted_Run_Time:: 28762* pragma Task_Info:: 28763* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 28764 28765@end menu 28766 28767@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 28768@anchor{gnat_rm/obsolescent_features id2}@anchor{436}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{437} 28769@section pragma No_Run_Time 28770 28771 28772The pragma @code{No_Run_Time} is used to achieve an affect similar 28773to the use of the "Zero Foot Print" configurable run time, but without 28774requiring a specially configured run time. The result of using this 28775pragma, which must be used for all units in a partition, is to restrict 28776the use of any language features requiring run-time support code. The 28777preferred usage is to use an appropriately configured run-time that 28778includes just those features that are to be made accessible. 28779 28780@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 28781@anchor{gnat_rm/obsolescent_features id3}@anchor{438}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{439} 28782@section pragma Ravenscar 28783 28784 28785The pragma @code{Ravenscar} has exactly the same effect as pragma 28786@code{Profile (Ravenscar)}. The latter usage is preferred since it 28787is part of the new Ada 2005 standard. 28788 28789@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 28790@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{43a}@anchor{gnat_rm/obsolescent_features id4}@anchor{43b} 28791@section pragma Restricted_Run_Time 28792 28793 28794The pragma @code{Restricted_Run_Time} has exactly the same effect as 28795pragma @code{Profile (Restricted)}. The latter usage is 28796preferred since the Ada 2005 pragma @code{Profile} is intended for 28797this kind of implementation dependent addition. 28798 28799@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 28800@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{43c}@anchor{gnat_rm/obsolescent_features id5}@anchor{43d} 28801@section pragma Task_Info 28802 28803 28804The functionality provided by pragma @code{Task_Info} is now part of the 28805Ada language. The @code{CPU} aspect and the package 28806@code{System.Multiprocessors} offer a less system-dependent way to specify 28807task affinity or to query the number of processors. 28808 28809Syntax 28810 28811@example 28812pragma Task_Info (EXPRESSION); 28813@end example 28814 28815This pragma appears within a task definition (like pragma 28816@code{Priority}) and applies to the task in which it appears. The 28817argument must be of type @code{System.Task_Info.Task_Info_Type}. 28818The @code{Task_Info} pragma provides system dependent control over 28819aspects of tasking implementation, for example, the ability to map 28820tasks to specific processors. For details on the facilities available 28821for the version of GNAT that you are using, see the documentation 28822in the spec of package System.Task_Info in the runtime 28823library. 28824 28825@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 28826@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{43e}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{43f} 28827@section package System.Task_Info (@code{s-tasinf.ads}) 28828 28829 28830This package provides target dependent functionality that is used 28831to support the @code{Task_Info} pragma. The predefined Ada package 28832@code{System.Multiprocessors} and the @code{CPU} aspect now provide a 28833standard replacement for GNAT's @code{Task_Info} functionality. 28834 28835@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 28836@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{440}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{441} 28837@chapter Compatibility and Porting Guide 28838 28839 28840This chapter presents some guidelines for developing portable Ada code, 28841describes the compatibility issues that may arise between 28842GNAT and other Ada compilation systems (including those for Ada 83), 28843and shows how GNAT can expedite porting 28844applications developed in other Ada environments. 28845 28846@menu 28847* Writing Portable Fixed-Point Declarations:: 28848* Compatibility with Ada 83:: 28849* Compatibility between Ada 95 and Ada 2005:: 28850* Implementation-dependent characteristics:: 28851* Compatibility with Other Ada Systems:: 28852* Representation Clauses:: 28853* Compatibility with HP Ada 83:: 28854 28855@end menu 28856 28857@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 28858@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{442}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{443} 28859@section Writing Portable Fixed-Point Declarations 28860 28861 28862The Ada Reference Manual gives an implementation freedom to choose bounds 28863that are narrower by @code{Small} from the given bounds. 28864For example, if we write 28865 28866@example 28867type F1 is delta 1.0 range -128.0 .. +128.0; 28868@end example 28869 28870then the implementation is allowed to choose -128.0 .. +127.0 if it 28871likes, but is not required to do so. 28872 28873This leads to possible portability problems, so let's have a closer 28874look at this, and figure out how to avoid these problems. 28875 28876First, why does this freedom exist, and why would an implementation 28877take advantage of it? To answer this, take a closer look at the type 28878declaration for @code{F1} above. If the compiler uses the given bounds, 28879it would need 9 bits to hold the largest positive value (and typically 28880that means 16 bits on all machines). But if the implementation chooses 28881the +127.0 bound then it can fit values of the type in 8 bits. 28882 28883Why not make the user write +127.0 if that's what is wanted? 28884The rationale is that if you are thinking of fixed point 28885as a kind of 'poor man's floating-point', then you don't want 28886to be thinking about the scaled integers that are used in its 28887representation. Let's take another example: 28888 28889@example 28890type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 28891@end example 28892 28893Looking at this declaration, it seems casually as though 28894it should fit in 16 bits, but again that extra positive value 28895+1.0 has the scaled integer equivalent of 2**15 which is one too 28896big for signed 16 bits. The implementation can treat this as: 28897 28898@example 28899type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 28900@end example 28901 28902and the Ada language design team felt that this was too annoying 28903to require. We don't need to debate this decision at this point, 28904since it is well established (the rule about narrowing the ranges 28905dates to Ada 83). 28906 28907But the important point is that an implementation is not required 28908to do this narrowing, so we have a potential portability problem. 28909We could imagine three types of implementation: 28910 28911 28912@enumerate a 28913 28914@item 28915those that narrow the range automatically if they can figure 28916out that the narrower range will allow storage in a smaller machine unit, 28917 28918@item 28919those that will narrow only if forced to by a @code{'Size} clause, and 28920 28921@item 28922those that will never narrow. 28923@end enumerate 28924 28925Now if we are language theoreticians, we can imagine a fourth 28926approach: to narrow all the time, e.g. to treat 28927 28928@example 28929type F3 is delta 1.0 range -10.0 .. +23.0; 28930@end example 28931 28932as though it had been written: 28933 28934@example 28935type F3 is delta 1.0 range -9.0 .. +22.0; 28936@end example 28937 28938But although technically allowed, such a behavior would be hostile and silly, 28939and no real compiler would do this. All real compilers will fall into one of 28940the categories (a), (b) or (c) above. 28941 28942So, how do you get the compiler to do what you want? The answer is give the 28943actual bounds you want, and then use a @code{'Small} clause and a 28944@code{'Size} clause to absolutely pin down what the compiler does. 28945E.g., for @code{F2} above, we will write: 28946 28947@example 28948My_Small : constant := 2.0**(-15); 28949My_First : constant := -1.0; 28950My_Last : constant := +1.0 - My_Small; 28951 28952type F2 is delta My_Small range My_First .. My_Last; 28953@end example 28954 28955and then add 28956 28957@example 28958for F2'Small use my_Small; 28959for F2'Size use 16; 28960@end example 28961 28962In practice all compilers will do the same thing here and will give you 28963what you want, so the above declarations are fully portable. If you really 28964want to play language lawyer and guard against ludicrous behavior by the 28965compiler you could add 28966 28967@example 28968Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 28969Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 28970@end example 28971 28972One or other or both are allowed to be illegal if the compiler is 28973behaving in a silly manner, but at least the silly compiler will not 28974get away with silently messing with your (very clear) intentions. 28975 28976If you follow this scheme you will be guaranteed that your fixed-point 28977types will be portable. 28978 28979@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 28980@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{445} 28981@section Compatibility with Ada 83 28982 28983 28984@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 28985 28986Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 28987are highly upwards compatible with Ada 83. In 28988particular, the design intention was that the difficulties associated 28989with moving from Ada 83 to later versions of the standard should be no greater 28990than those that occur when moving from one Ada 83 system to another. 28991 28992However, there are a number of points at which there are minor 28993incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 28994full details of these issues as they relate to Ada 95, 28995and should be consulted for a complete treatment. 28996In practice the 28997following subsections treat the most likely issues to be encountered. 28998 28999@menu 29000* Legal Ada 83 programs that are illegal in Ada 95:: 29001* More deterministic semantics:: 29002* Changed semantics:: 29003* Other language compatibility issues:: 29004 29005@end menu 29006 29007@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 29008@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{447} 29009@subsection Legal Ada 83 programs that are illegal in Ada 95 29010 29011 29012Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 29013Ada 95 and later versions of the standard: 29014 29015 29016@itemize * 29017 29018@item 29019@emph{Character literals} 29020 29021Some uses of character literals are ambiguous. Since Ada 95 has introduced 29022@code{Wide_Character} as a new predefined character type, some uses of 29023character literals that were legal in Ada 83 are illegal in Ada 95. 29024For example: 29025 29026@example 29027for Char in 'A' .. 'Z' loop ... end loop; 29028@end example 29029 29030The problem is that 'A' and 'Z' could be from either 29031@code{Character} or @code{Wide_Character}. The simplest correction 29032is to make the type explicit; e.g.: 29033 29034@example 29035for Char in Character range 'A' .. 'Z' loop ... end loop; 29036@end example 29037 29038@item 29039@emph{New reserved words} 29040 29041The identifiers @code{abstract}, @code{aliased}, @code{protected}, 29042@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. 29043Existing Ada 83 code using any of these identifiers must be edited to 29044use some alternative name. 29045 29046@item 29047@emph{Freezing rules} 29048 29049The rules in Ada 95 are slightly different with regard to the point at 29050which entities are frozen, and representation pragmas and clauses are 29051not permitted past the freeze point. This shows up most typically in 29052the form of an error message complaining that a representation item 29053appears too late, and the appropriate corrective action is to move 29054the item nearer to the declaration of the entity to which it refers. 29055 29056A particular case is that representation pragmas 29057cannot be applied to a subprogram body. If necessary, a separate subprogram 29058declaration must be introduced to which the pragma can be applied. 29059 29060@item 29061@emph{Optional bodies for library packages} 29062 29063In Ada 83, a package that did not require a package body was nevertheless 29064allowed to have one. This lead to certain surprises in compiling large 29065systems (situations in which the body could be unexpectedly ignored by the 29066binder). In Ada 95, if a package does not require a body then it is not 29067permitted to have a body. To fix this problem, simply remove a redundant 29068body if it is empty, or, if it is non-empty, introduce a dummy declaration 29069into the spec that makes the body required. One approach is to add a private 29070part to the package declaration (if necessary), and define a parameterless 29071procedure called @code{Requires_Body}, which must then be given a dummy 29072procedure body in the package body, which then becomes required. 29073Another approach (assuming that this does not introduce elaboration 29074circularities) is to add an @code{Elaborate_Body} pragma to the package spec, 29075since one effect of this pragma is to require the presence of a package body. 29076 29077@item 29078@emph{Numeric_Error is the same exception as Constraint_Error} 29079 29080In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. 29081This means that it is illegal to have separate exception handlers for 29082the two exceptions. The fix is simply to remove the handler for the 29083@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 29084@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). 29085 29086@item 29087@emph{Indefinite subtypes in generics} 29088 29089In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) 29090as the actual for a generic formal private type, but then the instantiation 29091would be illegal if there were any instances of declarations of variables 29092of this type in the generic body. In Ada 95, to avoid this clear violation 29093of the methodological principle known as the 'contract model', 29094the generic declaration explicitly indicates whether 29095or not such instantiations are permitted. If a generic formal parameter 29096has explicit unknown discriminants, indicated by using @code{(<>)} after the 29097subtype name, then it can be instantiated with indefinite types, but no 29098stand-alone variables can be declared of this type. Any attempt to declare 29099such a variable will result in an illegality at the time the generic is 29100declared. If the @code{(<>)} notation is not used, then it is illegal 29101to instantiate the generic with an indefinite type. 29102This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 29103It will show up as a compile time error, and 29104the fix is usually simply to add the @code{(<>)} to the generic declaration. 29105@end itemize 29106 29107@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 29108@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{449} 29109@subsection More deterministic semantics 29110 29111 29112 29113@itemize * 29114 29115@item 29116@emph{Conversions} 29117 29118Conversions from real types to integer types round away from 0. In Ada 83 29119the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 29120implementation freedom was intended to support unbiased rounding in 29121statistical applications, but in practice it interfered with portability. 29122In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 29123is required. Numeric code may be affected by this change in semantics. 29124Note, though, that this issue is no worse than already existed in Ada 83 29125when porting code from one vendor to another. 29126 29127@item 29128@emph{Tasking} 29129 29130The Real-Time Annex introduces a set of policies that define the behavior of 29131features that were implementation dependent in Ada 83, such as the order in 29132which open select branches are executed. 29133@end itemize 29134 29135@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 29136@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{44b} 29137@subsection Changed semantics 29138 29139 29140The worst kind of incompatibility is one where a program that is legal in 29141Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 29142possible in Ada 83. Fortunately this is extremely rare, but the one 29143situation that you should be alert to is the change in the predefined type 29144@code{Character} from 7-bit ASCII to 8-bit Latin-1. 29145 29146@quotation 29147 29148@geindex Latin-1 29149@end quotation 29150 29151 29152@itemize * 29153 29154@item 29155@emph{Range of type `@w{`}Character`@w{`}} 29156 29157The range of @code{Standard.Character} is now the full 256 characters 29158of Latin-1, whereas in most Ada 83 implementations it was restricted 29159to 128 characters. Although some of the effects of 29160this change will be manifest in compile-time rejection of legal 29161Ada 83 programs it is possible for a working Ada 83 program to have 29162a different effect in Ada 95, one that was not permitted in Ada 83. 29163As an example, the expression 29164@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now 29165delivers @code{255} as its value. 29166In general, you should look at the logic of any 29167character-processing Ada 83 program and see whether it needs to be adapted 29168to work correctly with Latin-1. Note that the predefined Ada 95 API has a 29169character handling package that may be relevant if code needs to be adapted 29170to account for the additional Latin-1 elements. 29171The desirable fix is to 29172modify the program to accommodate the full character set, but in some cases 29173it may be convenient to define a subtype or derived type of Character that 29174covers only the restricted range. 29175@end itemize 29176 29177@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 29178@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{44d} 29179@subsection Other language compatibility issues 29180 29181 29182 29183@itemize * 29184 29185@item 29186@emph{-gnat83} switch 29187 29188All implementations of GNAT provide a switch that causes GNAT to operate 29189in Ada 83 mode. In this mode, some but not all compatibility problems 29190of the type described above are handled automatically. For example, the 29191new reserved words introduced in Ada 95 and Ada 2005 are treated simply 29192as identifiers as in Ada 83. However, 29193in practice, it is usually advisable to make the necessary modifications 29194to the program to remove the need for using this switch. 29195See the @code{Compiling Different Versions of Ada} section in 29196the @cite{GNAT User's Guide}. 29197 29198@item 29199Support for removed Ada 83 pragmas and attributes 29200 29201A number of pragmas and attributes from Ada 83 were removed from Ada 95, 29202generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 29203compilers are allowed, but not required, to implement these missing 29204elements. In contrast with some other compilers, GNAT implements all 29205such pragmas and attributes, eliminating this compatibility concern. These 29206include @code{pragma Interface} and the floating point type attributes 29207(@code{Emax}, @code{Mantissa}, etc.), among other items. 29208@end itemize 29209 29210@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 29211@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{44f} 29212@section Compatibility between Ada 95 and Ada 2005 29213 29214 29215@geindex Compatibility between Ada 95 and Ada 2005 29216 29217Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 29218a number of incompatibilities. Several are enumerated below; 29219for a complete description please see the 29220@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 29221@cite{Rationale for Ada 2005}. 29222 29223 29224@itemize * 29225 29226@item 29227@emph{New reserved words.} 29228 29229The words @code{interface}, @code{overriding} and @code{synchronized} are 29230reserved in Ada 2005. 29231A pre-Ada 2005 program that uses any of these as an identifier will be 29232illegal. 29233 29234@item 29235@emph{New declarations in predefined packages.} 29236 29237A number of packages in the predefined environment contain new declarations: 29238@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, 29239@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, 29240@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, 29241@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, 29242@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. 29243If an Ada 95 program does a @code{with} and @code{use} of any of these 29244packages, the new declarations may cause name clashes. 29245 29246@item 29247@emph{Access parameters.} 29248 29249A nondispatching subprogram with an access parameter cannot be renamed 29250as a dispatching operation. This was permitted in Ada 95. 29251 29252@item 29253@emph{Access types, discriminants, and constraints.} 29254 29255Rule changes in this area have led to some incompatibilities; for example, 29256constrained subtypes of some access types are not permitted in Ada 2005. 29257 29258@item 29259@emph{Aggregates for limited types.} 29260 29261The allowance of aggregates for limited types in Ada 2005 raises the 29262possibility of ambiguities in legal Ada 95 programs, since additional types 29263now need to be considered in expression resolution. 29264 29265@item 29266@emph{Fixed-point multiplication and division.} 29267 29268Certain expressions involving '*' or '/' for a fixed-point type, which 29269were legal in Ada 95 and invoked the predefined versions of these operations, 29270are now ambiguous. 29271The ambiguity may be resolved either by applying a type conversion to the 29272expression, or by explicitly invoking the operation from package 29273@code{Standard}. 29274 29275@item 29276@emph{Return-by-reference types.} 29277 29278The Ada 95 return-by-reference mechanism has been removed. Instead, the user 29279can declare a function returning a value from an anonymous access type. 29280@end itemize 29281 29282@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 29283@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{451} 29284@section Implementation-dependent characteristics 29285 29286 29287Although the Ada language defines the semantics of each construct as 29288precisely as practical, in some situations (for example for reasons of 29289efficiency, or where the effect is heavily dependent on the host or target 29290platform) the implementation is allowed some freedom. In porting Ada 83 29291code to GNAT, you need to be aware of whether / how the existing code 29292exercised such implementation dependencies. Such characteristics fall into 29293several categories, and GNAT offers specific support in assisting the 29294transition from certain Ada 83 compilers. 29295 29296@menu 29297* Implementation-defined pragmas:: 29298* Implementation-defined attributes:: 29299* Libraries:: 29300* Elaboration order:: 29301* Target-specific aspects:: 29302 29303@end menu 29304 29305@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 29306@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{453} 29307@subsection Implementation-defined pragmas 29308 29309 29310Ada compilers are allowed to supplement the language-defined pragmas, and 29311these are a potential source of non-portability. All GNAT-defined pragmas 29312are described in @ref{7,,Implementation Defined Pragmas}, 29313and these include several that are specifically 29314intended to correspond to other vendors' Ada 83 pragmas. 29315For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. 29316For compatibility with HP Ada 83, GNAT supplies the pragmas 29317@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, 29318@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, 29319and @code{Volatile}. 29320Other relevant pragmas include @code{External} and @code{Link_With}. 29321Some vendor-specific 29322Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are 29323recognized, thus 29324avoiding compiler rejection of units that contain such pragmas; they are not 29325relevant in a GNAT context and hence are not otherwise implemented. 29326 29327@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 29328@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{455} 29329@subsection Implementation-defined attributes 29330 29331 29332Analogous to pragmas, the set of attributes may be extended by an 29333implementation. All GNAT-defined attributes are described in 29334@ref{8,,Implementation Defined Attributes}, 29335and these include several that are specifically intended 29336to correspond to other vendors' Ada 83 attributes. For migrating from VADS, 29337the attribute @code{VADS_Size} may be useful. For compatibility with HP 29338Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and 29339@code{Type_Class}. 29340 29341@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 29342@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{457} 29343@subsection Libraries 29344 29345 29346Vendors may supply libraries to supplement the standard Ada API. If Ada 83 29347code uses vendor-specific libraries then there are several ways to manage 29348this in Ada 95 and later versions of the standard: 29349 29350 29351@itemize * 29352 29353@item 29354If the source code for the libraries (specs and bodies) are 29355available, then the libraries can be migrated in the same way as the 29356application. 29357 29358@item 29359If the source code for the specs but not the bodies are 29360available, then you can reimplement the bodies. 29361 29362@item 29363Some features introduced by Ada 95 obviate the need for library support. For 29364example most Ada 83 vendors supplied a package for unsigned integers. The 29365Ada 95 modular type feature is the preferred way to handle this need, so 29366instead of migrating or reimplementing the unsigned integer package it may 29367be preferable to retrofit the application using modular types. 29368@end itemize 29369 29370@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 29371@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{459} 29372@subsection Elaboration order 29373 29374 29375The implementation can choose any elaboration order consistent with the unit 29376dependency relationship. This freedom means that some orders can result in 29377Program_Error being raised due to an 'Access Before Elaboration': an attempt 29378to invoke a subprogram before its body has been elaborated, or to instantiate 29379a generic before the generic body has been elaborated. By default GNAT 29380attempts to choose a safe order (one that will not encounter access before 29381elaboration problems) by implicitly inserting @code{Elaborate} or 29382@code{Elaborate_All} pragmas where 29383needed. However, this can lead to the creation of elaboration circularities 29384and a resulting rejection of the program by gnatbind. This issue is 29385thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix 29386in the @cite{GNAT User's Guide}. 29387In brief, there are several 29388ways to deal with this situation: 29389 29390 29391@itemize * 29392 29393@item 29394Modify the program to eliminate the circularities, e.g., by moving 29395elaboration-time code into explicitly-invoked procedures 29396 29397@item 29398Constrain the elaboration order by including explicit @code{Elaborate_Body} or 29399@code{Elaborate} pragmas, and then inhibit the generation of implicit 29400@code{Elaborate_All} 29401pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 29402(by selectively suppressing elaboration checks via pragma 29403@code{Suppress(Elaboration_Check)} when it is safe to do so). 29404@end itemize 29405 29406@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 29407@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{45b} 29408@subsection Target-specific aspects 29409 29410 29411Low-level applications need to deal with machine addresses, data 29412representations, interfacing with assembler code, and similar issues. If 29413such an Ada 83 application is being ported to different target hardware (for 29414example where the byte endianness has changed) then you will need to 29415carefully examine the program logic; the porting effort will heavily depend 29416on the robustness of the original design. Moreover, Ada 95 (and thus 29417Ada 2005 and Ada 2012) are sometimes 29418incompatible with typical Ada 83 compiler practices regarding implicit 29419packing, the meaning of the Size attribute, and the size of access values. 29420GNAT's approach to these issues is described in @ref{45c,,Representation Clauses}. 29421 29422@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 29423@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{45e} 29424@section Compatibility with Other Ada Systems 29425 29426 29427If programs avoid the use of implementation dependent and 29428implementation defined features, as documented in the 29429@cite{Ada Reference Manual}, there should be a high degree of portability between 29430GNAT and other Ada systems. The following are specific items which 29431have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 29432compilers, but do not affect porting code to GNAT. 29433(As of January 2007, GNAT is the only compiler available for Ada 2005; 29434the following issues may or may not arise for Ada 2005 programs 29435when other compilers appear.) 29436 29437 29438@itemize * 29439 29440@item 29441@emph{Ada 83 Pragmas and Attributes} 29442 29443Ada 95 compilers are allowed, but not required, to implement the missing 29444Ada 83 pragmas and attributes that are no longer defined in Ada 95. 29445GNAT implements all such pragmas and attributes, eliminating this as 29446a compatibility concern, but some other Ada 95 compilers reject these 29447pragmas and attributes. 29448 29449@item 29450@emph{Specialized Needs Annexes} 29451 29452GNAT implements the full set of special needs annexes. At the 29453current time, it is the only Ada 95 compiler to do so. This means that 29454programs making use of these features may not be portable to other Ada 2945595 compilation systems. 29456 29457@item 29458@emph{Representation Clauses} 29459 29460Some other Ada 95 compilers implement only the minimal set of 29461representation clauses required by the Ada 95 reference manual. GNAT goes 29462far beyond this minimal set, as described in the next section. 29463@end itemize 29464 29465@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 29466@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{45f} 29467@section Representation Clauses 29468 29469 29470The Ada 83 reference manual was quite vague in describing both the minimal 29471required implementation of representation clauses, and also their precise 29472effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 29473minimal set of capabilities required is still quite limited. 29474 29475GNAT implements the full required set of capabilities in 29476Ada 95 and Ada 2005, but also goes much further, and in particular 29477an effort has been made to be compatible with existing Ada 83 usage to the 29478greatest extent possible. 29479 29480A few cases exist in which Ada 83 compiler behavior is incompatible with 29481the requirements in Ada 95 (and thus also Ada 2005). These are instances of 29482intentional or accidental dependence on specific implementation dependent 29483characteristics of these Ada 83 compilers. The following is a list of 29484the cases most likely to arise in existing Ada 83 code. 29485 29486 29487@itemize * 29488 29489@item 29490@emph{Implicit Packing} 29491 29492Some Ada 83 compilers allowed a Size specification to cause implicit 29493packing of an array or record. This could cause expensive implicit 29494conversions for change of representation in the presence of derived 29495types, and the Ada design intends to avoid this possibility. 29496Subsequent AI's were issued to make it clear that such implicit 29497change of representation in response to a Size clause is inadvisable, 29498and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 29499Reference Manuals as implementation advice that is followed by GNAT. 29500The problem will show up as an error 29501message rejecting the size clause. The fix is simply to provide 29502the explicit pragma @code{Pack}, or for more fine tuned control, provide 29503a Component_Size clause. 29504 29505@item 29506@emph{Meaning of Size Attribute} 29507 29508The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 29509the minimal number of bits required to hold values of the type. For example, 29510on a 32-bit machine, the size of @code{Natural} will typically be 31 and not 2951132 (since no sign bit is required). Some Ada 83 compilers gave 31, and 29512some 32 in this situation. This problem will usually show up as a compile 29513time error, but not always. It is a good idea to check all uses of the 29514'Size attribute when porting Ada 83 code. The GNAT specific attribute 29515Object_Size can provide a useful way of duplicating the behavior of 29516some Ada 83 compiler systems. 29517 29518@item 29519@emph{Size of Access Types} 29520 29521A common assumption in Ada 83 code is that an access type is in fact a pointer, 29522and that therefore it will be the same size as a System.Address value. This 29523assumption is true for GNAT in most cases with one exception. For the case of 29524a pointer to an unconstrained array type (where the bounds may vary from one 29525value of the access type to another), the default is to use a 'fat pointer', 29526which is represented as two separate pointers, one to the bounds, and one to 29527the array. This representation has a number of advantages, including improved 29528efficiency. However, it may cause some difficulties in porting existing Ada 83 29529code which makes the assumption that, for example, pointers fit in 32 bits on 29530a machine with 32-bit addressing. 29531 29532To get around this problem, GNAT also permits the use of 'thin pointers' for 29533access types in this case (where the designated type is an unconstrained array 29534type). These thin pointers are indeed the same size as a System.Address value. 29535To specify a thin pointer, use a size clause for the type, for example: 29536 29537@example 29538type X is access all String; 29539for X'Size use Standard'Address_Size; 29540@end example 29541 29542which will cause the type X to be represented using a single pointer. 29543When using this representation, the bounds are right behind the array. 29544This representation is slightly less efficient, and does not allow quite 29545such flexibility in the use of foreign pointers or in using the 29546Unrestricted_Access attribute to create pointers to non-aliased objects. 29547But for any standard portable use of the access type it will work in 29548a functionally correct manner and allow porting of existing code. 29549Note that another way of forcing a thin pointer representation 29550is to use a component size clause for the element size in an array, 29551or a record representation clause for an access field in a record. 29552 29553See the documentation of Unrestricted_Access in the GNAT RM for a 29554full discussion of possible problems using this attribute in conjunction 29555with thin pointers. 29556@end itemize 29557 29558@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 29559@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{461} 29560@section Compatibility with HP Ada 83 29561 29562 29563All the HP Ada 83 pragmas and attributes are recognized, although only a subset 29564of them can sensibly be implemented. The description of pragmas in 29565@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 29566applicable to GNAT. 29567 29568 29569@itemize * 29570 29571@item 29572@emph{Default floating-point representation} 29573 29574In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 29575it is VMS format. 29576 29577@item 29578@emph{System} 29579 29580the package System in GNAT exactly corresponds to the definition in the 29581Ada 95 reference manual, which means that it excludes many of the 29582HP Ada 83 extensions. However, a separate package Aux_DEC is provided 29583that contains the additional definitions, and a special pragma, 29584Extend_System allows this package to be treated transparently as an 29585extension of package System. 29586@end itemize 29587 29588@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 29589@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{462}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{463} 29590@chapter GNU Free Documentation License 29591 29592 29593Version 1.3, 3 November 2008 29594 29595Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 29596@indicateurl{http://fsf.org/} 29597 29598Everyone is permitted to copy and distribute verbatim copies of this 29599license document, but changing it is not allowed. 29600 29601@strong{Preamble} 29602 29603The purpose of this License is to make a manual, textbook, or other 29604functional and useful document "free" in the sense of freedom: to 29605assure everyone the effective freedom to copy and redistribute it, 29606with or without modifying it, either commercially or noncommercially. 29607Secondarily, this License preserves for the author and publisher a way 29608to get credit for their work, while not being considered responsible 29609for modifications made by others. 29610 29611This License is a kind of "copyleft", which means that derivative 29612works of the document must themselves be free in the same sense. It 29613complements the GNU General Public License, which is a copyleft 29614license designed for free software. 29615 29616We have designed this License in order to use it for manuals for free 29617software, because free software needs free documentation: a free 29618program should come with manuals providing the same freedoms that the 29619software does. But this License is not limited to software manuals; 29620it can be used for any textual work, regardless of subject matter or 29621whether it is published as a printed book. We recommend this License 29622principally for works whose purpose is instruction or reference. 29623 29624@strong{1. APPLICABILITY AND DEFINITIONS} 29625 29626This License applies to any manual or other work, in any medium, that 29627contains a notice placed by the copyright holder saying it can be 29628distributed under the terms of this License. Such a notice grants a 29629world-wide, royalty-free license, unlimited in duration, to use that 29630work under the conditions stated herein. The @strong{Document}, below, 29631refers to any such manual or work. Any member of the public is a 29632licensee, and is addressed as "@strong{you}". You accept the license if you 29633copy, modify or distribute the work in a way requiring permission 29634under copyright law. 29635 29636A "@strong{Modified Version}" of the Document means any work containing the 29637Document or a portion of it, either copied verbatim, or with 29638modifications and/or translated into another language. 29639 29640A "@strong{Secondary Section}" is a named appendix or a front-matter section of 29641the Document that deals exclusively with the relationship of the 29642publishers or authors of the Document to the Document's overall subject 29643(or to related matters) and contains nothing that could fall directly 29644within that overall subject. (Thus, if the Document is in part a 29645textbook of mathematics, a Secondary Section may not explain any 29646mathematics.) The relationship could be a matter of historical 29647connection with the subject or with related matters, or of legal, 29648commercial, philosophical, ethical or political position regarding 29649them. 29650 29651The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 29652are designated, as being those of Invariant Sections, in the notice 29653that says that the Document is released under this License. If a 29654section does not fit the above definition of Secondary then it is not 29655allowed to be designated as Invariant. The Document may contain zero 29656Invariant Sections. If the Document does not identify any Invariant 29657Sections then there are none. 29658 29659The "@strong{Cover Texts}" are certain short passages of text that are listed, 29660as Front-Cover Texts or Back-Cover Texts, in the notice that says that 29661the Document is released under this License. A Front-Cover Text may 29662be at most 5 words, and a Back-Cover Text may be at most 25 words. 29663 29664A "@strong{Transparent}" copy of the Document means a machine-readable copy, 29665represented in a format whose specification is available to the 29666general public, that is suitable for revising the document 29667straightforwardly with generic text editors or (for images composed of 29668pixels) generic paint programs or (for drawings) some widely available 29669drawing editor, and that is suitable for input to text formatters or 29670for automatic translation to a variety of formats suitable for input 29671to text formatters. A copy made in an otherwise Transparent file 29672format whose markup, or absence of markup, has been arranged to thwart 29673or discourage subsequent modification by readers is not Transparent. 29674An image format is not Transparent if used for any substantial amount 29675of text. A copy that is not "Transparent" is called @strong{Opaque}. 29676 29677Examples of suitable formats for Transparent copies include plain 29678ASCII without markup, Texinfo input format, LaTeX input format, SGML 29679or XML using a publicly available DTD, and standard-conforming simple 29680HTML, PostScript or PDF designed for human modification. Examples of 29681transparent image formats include PNG, XCF and JPG. Opaque formats 29682include proprietary formats that can be read and edited only by 29683proprietary word processors, SGML or XML for which the DTD and/or 29684processing tools are not generally available, and the 29685machine-generated HTML, PostScript or PDF produced by some word 29686processors for output purposes only. 29687 29688The "@strong{Title Page}" means, for a printed book, the title page itself, 29689plus such following pages as are needed to hold, legibly, the material 29690this License requires to appear in the title page. For works in 29691formats which do not have any title page as such, "Title Page" means 29692the text near the most prominent appearance of the work's title, 29693preceding the beginning of the body of the text. 29694 29695The "@strong{publisher}" means any person or entity that distributes 29696copies of the Document to the public. 29697 29698A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 29699title either is precisely XYZ or contains XYZ in parentheses following 29700text that translates XYZ in another language. (Here XYZ stands for a 29701specific section name mentioned below, such as "@strong{Acknowledgements}", 29702"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 29703To "@strong{Preserve the Title}" 29704of such a section when you modify the Document means that it remains a 29705section "Entitled XYZ" according to this definition. 29706 29707The Document may include Warranty Disclaimers next to the notice which 29708states that this License applies to the Document. These Warranty 29709Disclaimers are considered to be included by reference in this 29710License, but only as regards disclaiming warranties: any other 29711implication that these Warranty Disclaimers may have is void and has 29712no effect on the meaning of this License. 29713 29714@strong{2. VERBATIM COPYING} 29715 29716You may copy and distribute the Document in any medium, either 29717commercially or noncommercially, provided that this License, the 29718copyright notices, and the license notice saying this License applies 29719to the Document are reproduced in all copies, and that you add no other 29720conditions whatsoever to those of this License. You may not use 29721technical measures to obstruct or control the reading or further 29722copying of the copies you make or distribute. However, you may accept 29723compensation in exchange for copies. If you distribute a large enough 29724number of copies you must also follow the conditions in section 3. 29725 29726You may also lend copies, under the same conditions stated above, and 29727you may publicly display copies. 29728 29729@strong{3. COPYING IN QUANTITY} 29730 29731If you publish printed copies (or copies in media that commonly have 29732printed covers) of the Document, numbering more than 100, and the 29733Document's license notice requires Cover Texts, you must enclose the 29734copies in covers that carry, clearly and legibly, all these Cover 29735Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 29736the back cover. Both covers must also clearly and legibly identify 29737you as the publisher of these copies. The front cover must present 29738the full title with all words of the title equally prominent and 29739visible. You may add other material on the covers in addition. 29740Copying with changes limited to the covers, as long as they preserve 29741the title of the Document and satisfy these conditions, can be treated 29742as verbatim copying in other respects. 29743 29744If the required texts for either cover are too voluminous to fit 29745legibly, you should put the first ones listed (as many as fit 29746reasonably) on the actual cover, and continue the rest onto adjacent 29747pages. 29748 29749If you publish or distribute Opaque copies of the Document numbering 29750more than 100, you must either include a machine-readable Transparent 29751copy along with each Opaque copy, or state in or with each Opaque copy 29752a computer-network location from which the general network-using 29753public has access to download using public-standard network protocols 29754a complete Transparent copy of the Document, free of added material. 29755If you use the latter option, you must take reasonably prudent steps, 29756when you begin distribution of Opaque copies in quantity, to ensure 29757that this Transparent copy will remain thus accessible at the stated 29758location until at least one year after the last time you distribute an 29759Opaque copy (directly or through your agents or retailers) of that 29760edition to the public. 29761 29762It is requested, but not required, that you contact the authors of the 29763Document well before redistributing any large number of copies, to give 29764them a chance to provide you with an updated version of the Document. 29765 29766@strong{4. MODIFICATIONS} 29767 29768You may copy and distribute a Modified Version of the Document under 29769the conditions of sections 2 and 3 above, provided that you release 29770the Modified Version under precisely this License, with the Modified 29771Version filling the role of the Document, thus licensing distribution 29772and modification of the Modified Version to whoever possesses a copy 29773of it. In addition, you must do these things in the Modified Version: 29774 29775 29776@enumerate A 29777 29778@item 29779Use in the Title Page (and on the covers, if any) a title distinct 29780from that of the Document, and from those of previous versions 29781(which should, if there were any, be listed in the History section 29782of the Document). You may use the same title as a previous version 29783if the original publisher of that version gives permission. 29784 29785@item 29786List on the Title Page, as authors, one or more persons or entities 29787responsible for authorship of the modifications in the Modified 29788Version, together with at least five of the principal authors of the 29789Document (all of its principal authors, if it has fewer than five), 29790unless they release you from this requirement. 29791 29792@item 29793State on the Title page the name of the publisher of the 29794Modified Version, as the publisher. 29795 29796@item 29797Preserve all the copyright notices of the Document. 29798 29799@item 29800Add an appropriate copyright notice for your modifications 29801adjacent to the other copyright notices. 29802 29803@item 29804Include, immediately after the copyright notices, a license notice 29805giving the public permission to use the Modified Version under the 29806terms of this License, in the form shown in the Addendum below. 29807 29808@item 29809Preserve in that license notice the full lists of Invariant Sections 29810and required Cover Texts given in the Document's license notice. 29811 29812@item 29813Include an unaltered copy of this License. 29814 29815@item 29816Preserve the section Entitled "History", Preserve its Title, and add 29817to it an item stating at least the title, year, new authors, and 29818publisher of the Modified Version as given on the Title Page. If 29819there is no section Entitled "History" in the Document, create one 29820stating the title, year, authors, and publisher of the Document as 29821given on its Title Page, then add an item describing the Modified 29822Version as stated in the previous sentence. 29823 29824@item 29825Preserve the network location, if any, given in the Document for 29826public access to a Transparent copy of the Document, and likewise 29827the network locations given in the Document for previous versions 29828it was based on. These may be placed in the "History" section. 29829You may omit a network location for a work that was published at 29830least four years before the Document itself, or if the original 29831publisher of the version it refers to gives permission. 29832 29833@item 29834For any section Entitled "Acknowledgements" or "Dedications", 29835Preserve the Title of the section, and preserve in the section all 29836the substance and tone of each of the contributor acknowledgements 29837and/or dedications given therein. 29838 29839@item 29840Preserve all the Invariant Sections of the Document, 29841unaltered in their text and in their titles. Section numbers 29842or the equivalent are not considered part of the section titles. 29843 29844@item 29845Delete any section Entitled "Endorsements". Such a section 29846may not be included in the Modified Version. 29847 29848@item 29849Do not retitle any existing section to be Entitled "Endorsements" 29850or to conflict in title with any Invariant Section. 29851 29852@item 29853Preserve any Warranty Disclaimers. 29854@end enumerate 29855 29856If the Modified Version includes new front-matter sections or 29857appendices that qualify as Secondary Sections and contain no material 29858copied from the Document, you may at your option designate some or all 29859of these sections as invariant. To do this, add their titles to the 29860list of Invariant Sections in the Modified Version's license notice. 29861These titles must be distinct from any other section titles. 29862 29863You may add a section Entitled "Endorsements", provided it contains 29864nothing but endorsements of your Modified Version by various 29865parties---for example, statements of peer review or that the text has 29866been approved by an organization as the authoritative definition of a 29867standard. 29868 29869You may add a passage of up to five words as a Front-Cover Text, and a 29870passage of up to 25 words as a Back-Cover Text, to the end of the list 29871of Cover Texts in the Modified Version. Only one passage of 29872Front-Cover Text and one of Back-Cover Text may be added by (or 29873through arrangements made by) any one entity. If the Document already 29874includes a cover text for the same cover, previously added by you or 29875by arrangement made by the same entity you are acting on behalf of, 29876you may not add another; but you may replace the old one, on explicit 29877permission from the previous publisher that added the old one. 29878 29879The author(s) and publisher(s) of the Document do not by this License 29880give permission to use their names for publicity for or to assert or 29881imply endorsement of any Modified Version. 29882 29883@strong{5. COMBINING DOCUMENTS} 29884 29885You may combine the Document with other documents released under this 29886License, under the terms defined in section 4 above for modified 29887versions, provided that you include in the combination all of the 29888Invariant Sections of all of the original documents, unmodified, and 29889list them all as Invariant Sections of your combined work in its 29890license notice, and that you preserve all their Warranty Disclaimers. 29891 29892The combined work need only contain one copy of this License, and 29893multiple identical Invariant Sections may be replaced with a single 29894copy. If there are multiple Invariant Sections with the same name but 29895different contents, make the title of each such section unique by 29896adding at the end of it, in parentheses, the name of the original 29897author or publisher of that section if known, or else a unique number. 29898Make the same adjustment to the section titles in the list of 29899Invariant Sections in the license notice of the combined work. 29900 29901In the combination, you must combine any sections Entitled "History" 29902in the various original documents, forming one section Entitled 29903"History"; likewise combine any sections Entitled "Acknowledgements", 29904and any sections Entitled "Dedications". You must delete all sections 29905Entitled "Endorsements". 29906 29907@strong{6. COLLECTIONS OF DOCUMENTS} 29908 29909You may make a collection consisting of the Document and other documents 29910released under this License, and replace the individual copies of this 29911License in the various documents with a single copy that is included in 29912the collection, provided that you follow the rules of this License for 29913verbatim copying of each of the documents in all other respects. 29914 29915You may extract a single document from such a collection, and distribute 29916it individually under this License, provided you insert a copy of this 29917License into the extracted document, and follow this License in all 29918other respects regarding verbatim copying of that document. 29919 29920@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29921 29922A compilation of the Document or its derivatives with other separate 29923and independent documents or works, in or on a volume of a storage or 29924distribution medium, is called an "aggregate" if the copyright 29925resulting from the compilation is not used to limit the legal rights 29926of the compilation's users beyond what the individual works permit. 29927When the Document is included in an aggregate, this License does not 29928apply to the other works in the aggregate which are not themselves 29929derivative works of the Document. 29930 29931If the Cover Text requirement of section 3 is applicable to these 29932copies of the Document, then if the Document is less than one half of 29933the entire aggregate, the Document's Cover Texts may be placed on 29934covers that bracket the Document within the aggregate, or the 29935electronic equivalent of covers if the Document is in electronic form. 29936Otherwise they must appear on printed covers that bracket the whole 29937aggregate. 29938 29939@strong{8. TRANSLATION} 29940 29941Translation is considered a kind of modification, so you may 29942distribute translations of the Document under the terms of section 4. 29943Replacing Invariant Sections with translations requires special 29944permission from their copyright holders, but you may include 29945translations of some or all Invariant Sections in addition to the 29946original versions of these Invariant Sections. You may include a 29947translation of this License, and all the license notices in the 29948Document, and any Warranty Disclaimers, provided that you also include 29949the original English version of this License and the original versions 29950of those notices and disclaimers. In case of a disagreement between 29951the translation and the original version of this License or a notice 29952or disclaimer, the original version will prevail. 29953 29954If a section in the Document is Entitled "Acknowledgements", 29955"Dedications", or "History", the requirement (section 4) to Preserve 29956its Title (section 1) will typically require changing the actual 29957title. 29958 29959@strong{9. TERMINATION} 29960 29961You may not copy, modify, sublicense, or distribute the Document 29962except as expressly provided under this License. Any attempt 29963otherwise to copy, modify, sublicense, or distribute it is void, and 29964will automatically terminate your rights under this License. 29965 29966However, if you cease all violation of this License, then your license 29967from a particular copyright holder is reinstated (a) provisionally, 29968unless and until the copyright holder explicitly and finally 29969terminates your license, and (b) permanently, if the copyright holder 29970fails to notify you of the violation by some reasonable means prior to 2997160 days after the cessation. 29972 29973Moreover, your license from a particular copyright holder is 29974reinstated permanently if the copyright holder notifies you of the 29975violation by some reasonable means, this is the first time you have 29976received notice of violation of this License (for any work) from that 29977copyright holder, and you cure the violation prior to 30 days after 29978your receipt of the notice. 29979 29980Termination of your rights under this section does not terminate the 29981licenses of parties who have received copies or rights from you under 29982this License. If your rights have been terminated and not permanently 29983reinstated, receipt of a copy of some or all of the same material does 29984not give you any rights to use it. 29985 29986@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29987 29988The Free Software Foundation may publish new, revised versions 29989of the GNU Free Documentation License from time to time. Such new 29990versions will be similar in spirit to the present version, but may 29991differ in detail to address new problems or concerns. See 29992@indicateurl{http://www.gnu.org/copyleft/}. 29993 29994Each version of the License is given a distinguishing version number. 29995If the Document specifies that a particular numbered version of this 29996License "or any later version" applies to it, you have the option of 29997following the terms and conditions either of that specified version or 29998of any later version that has been published (not as a draft) by the 29999Free Software Foundation. If the Document does not specify a version 30000number of this License, you may choose any version ever published (not 30001as a draft) by the Free Software Foundation. If the Document 30002specifies that a proxy can decide which future versions of this 30003License can be used, that proxy's public statement of acceptance of a 30004version permanently authorizes you to choose that version for the 30005Document. 30006 30007@strong{11. RELICENSING} 30008 30009"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 30010World Wide Web server that publishes copyrightable works and also 30011provides prominent facilities for anybody to edit those works. A 30012public wiki that anybody can edit is an example of such a server. A 30013"Massive Multiauthor Collaboration" (or "MMC") contained in the 30014site means any set of copyrightable works thus published on the MMC 30015site. 30016 30017"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 30018license published by Creative Commons Corporation, a not-for-profit 30019corporation with a principal place of business in San Francisco, 30020California, as well as future copyleft versions of that license 30021published by that same organization. 30022 30023"Incorporate" means to publish or republish a Document, in whole or 30024in part, as part of another Document. 30025 30026An MMC is "eligible for relicensing" if it is licensed under this 30027License, and if all works that were first published under this License 30028somewhere other than this MMC, and subsequently incorporated in whole 30029or in part into the MMC, (1) had no cover texts or invariant sections, 30030and (2) were thus incorporated prior to November 1, 2008. 30031 30032The operator of an MMC Site may republish an MMC contained in the site 30033under CC-BY-SA on the same site at any time before August 1, 2009, 30034provided the MMC is eligible for relicensing. 30035 30036@strong{ADDENDUM: How to use this License for your documents} 30037 30038To use this License in a document you have written, include a copy of 30039the License in the document and put the following copyright and 30040license notices just after the title page: 30041 30042@quotation 30043 30044Copyright © YEAR YOUR NAME. 30045Permission is granted to copy, distribute and/or modify this document 30046under the terms of the GNU Free Documentation License, Version 1.3 30047or any later version published by the Free Software Foundation; 30048with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 30049A copy of the license is included in the section entitled "GNU 30050Free Documentation License". 30051@end quotation 30052 30053If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 30054replace the "with ... Texts." line with this: 30055 30056@quotation 30057 30058with the Invariant Sections being LIST THEIR TITLES, with the 30059Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 30060@end quotation 30061 30062If you have Invariant Sections without Cover Texts, or some other 30063combination of the three, merge those two alternatives to suit the 30064situation. 30065 30066If your document contains nontrivial examples of program code, we 30067recommend releasing these examples in parallel under your choice of 30068free software license, such as the GNU General Public License, 30069to permit their use in free software. 30070 30071@node Index,,GNU Free Documentation License,Top 30072@unnumbered Index 30073 30074 30075@printindex ge 30076 30077 30078@c %**end of body 30079@bye 30080