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 , Jan 10, 2018 25 26AdaCore 27 28Copyright @copyright{} 2008-2018, Free Software Foundation 29@end quotation 30 31@end copying 32 33@titlepage 34@title GNAT Reference Manual 35@insertcopying 36@end titlepage 37@contents 38 39@c %** start of user preamble 40 41@c %** end of user preamble 42 43@ifnottex 44@node Top 45@top GNAT Reference Manual 46@insertcopying 47@end ifnottex 48 49@c %**start of body 50@anchor{gnat_rm doc}@anchor{0} 51@emph{GNAT, The GNU Ada Development Environment} 52 53 54@include gcc-common.texi 55GCC version @value{version-GCC}@* 56AdaCore 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.3 or 60any later version published by the Free Software Foundation; with no 61Invariant Sections, with the Front-Cover Texts being "GNAT Reference 62Manual", and with no Back-Cover Texts. A copy of the license is 63included in the section entitled @ref{1,,GNU Free Documentation License}. 64 65@menu 66* About This Guide:: 67* Implementation Defined Pragmas:: 68* Implementation Defined Aspects:: 69* Implementation Defined Attributes:: 70* Standard and Implementation Defined Restrictions:: 71* Implementation Advice:: 72* Implementation Defined Characteristics:: 73* Intrinsic Subprograms:: 74* Representation Clauses and Pragmas:: 75* Standard Library Routines:: 76* The Implementation of Standard I/O:: 77* The GNAT Library:: 78* Interfacing to Other Languages:: 79* Specialized Needs Annexes:: 80* Implementation of Specific Ada Features:: 81* Implementation of Ada 2012 Features:: 82* Obsolescent Features:: 83* Compatibility and Porting Guide:: 84* GNU Free Documentation License:: 85* Index:: 86 87@detailmenu 88 --- The Detailed Node Listing --- 89 90About This Guide 91 92* What This Reference Manual Contains:: 93* Conventions:: 94* Related Information:: 95 96Implementation Defined Pragmas 97 98* Pragma Abort_Defer:: 99* Pragma Abstract_State:: 100* Pragma Ada_83:: 101* Pragma Ada_95:: 102* Pragma Ada_05:: 103* Pragma Ada_2005:: 104* Pragma Ada_12:: 105* Pragma Ada_2012:: 106* Pragma Allow_Integer_Address:: 107* Pragma Annotate:: 108* Pragma Assert:: 109* Pragma Assert_And_Cut:: 110* Pragma Assertion_Policy:: 111* Pragma Assume:: 112* Pragma Assume_No_Invalid_Values:: 113* Pragma Async_Readers:: 114* Pragma Async_Writers:: 115* Pragma Attribute_Definition:: 116* Pragma C_Pass_By_Copy:: 117* Pragma Check:: 118* Pragma Check_Float_Overflow:: 119* Pragma Check_Name:: 120* Pragma Check_Policy:: 121* Pragma Comment:: 122* Pragma Common_Object:: 123* Pragma Compile_Time_Error:: 124* Pragma Compile_Time_Warning:: 125* Pragma Compiler_Unit:: 126* Pragma Compiler_Unit_Warning:: 127* Pragma Complete_Representation:: 128* Pragma Complex_Representation:: 129* Pragma Component_Alignment:: 130* Pragma Constant_After_Elaboration:: 131* Pragma Contract_Cases:: 132* Pragma Convention_Identifier:: 133* Pragma CPP_Class:: 134* Pragma CPP_Constructor:: 135* Pragma CPP_Virtual:: 136* Pragma CPP_Vtable:: 137* Pragma CPU:: 138* Pragma Deadline_Floor:: 139* Pragma Default_Initial_Condition:: 140* Pragma Debug:: 141* Pragma Debug_Policy:: 142* Pragma Default_Scalar_Storage_Order:: 143* Pragma Default_Storage_Pool:: 144* Pragma Depends:: 145* Pragma Detect_Blocking:: 146* Pragma Disable_Atomic_Synchronization:: 147* Pragma Dispatching_Domain:: 148* Pragma Effective_Reads:: 149* Pragma Effective_Writes:: 150* Pragma Elaboration_Checks:: 151* Pragma Eliminate:: 152* Pragma Enable_Atomic_Synchronization:: 153* Pragma Export_Function:: 154* Pragma Export_Object:: 155* Pragma Export_Procedure:: 156* Pragma Export_Value:: 157* Pragma Export_Valued_Procedure:: 158* Pragma Extend_System:: 159* Pragma Extensions_Allowed:: 160* Pragma Extensions_Visible:: 161* Pragma External:: 162* Pragma External_Name_Casing:: 163* Pragma Fast_Math:: 164* Pragma Favor_Top_Level:: 165* Pragma Finalize_Storage_Only:: 166* Pragma Float_Representation:: 167* Pragma Ghost:: 168* Pragma Global:: 169* Pragma Ident:: 170* Pragma Ignore_Pragma:: 171* Pragma Implementation_Defined:: 172* Pragma Implemented:: 173* Pragma Implicit_Packing:: 174* Pragma Import_Function:: 175* Pragma Import_Object:: 176* Pragma Import_Procedure:: 177* Pragma Import_Valued_Procedure:: 178* Pragma Independent:: 179* Pragma Independent_Components:: 180* Pragma Initial_Condition:: 181* Pragma Initialize_Scalars:: 182* Pragma Initializes:: 183* Pragma Inline_Always:: 184* Pragma Inline_Generic:: 185* Pragma Interface:: 186* Pragma Interface_Name:: 187* Pragma Interrupt_Handler:: 188* Pragma Interrupt_State:: 189* Pragma Invariant:: 190* Pragma Keep_Names:: 191* Pragma License:: 192* Pragma Link_With:: 193* Pragma Linker_Alias:: 194* Pragma Linker_Constructor:: 195* Pragma Linker_Destructor:: 196* Pragma Linker_Section:: 197* Pragma Lock_Free:: 198* Pragma Loop_Invariant:: 199* Pragma Loop_Optimize:: 200* Pragma Loop_Variant:: 201* Pragma Machine_Attribute:: 202* Pragma Main:: 203* Pragma Main_Storage:: 204* Pragma Max_Queue_Length:: 205* Pragma No_Body:: 206* Pragma No_Component_Reordering:: 207* Pragma No_Elaboration_Code_All:: 208* Pragma No_Heap_Finalization:: 209* Pragma No_Inline:: 210* Pragma No_Return:: 211* Pragma No_Run_Time:: 212* Pragma No_Strict_Aliasing:: 213* Pragma No_Tagged_Streams:: 214* Pragma Normalize_Scalars:: 215* Pragma Obsolescent:: 216* Pragma Optimize_Alignment:: 217* Pragma Ordered:: 218* Pragma Overflow_Mode:: 219* Pragma Overriding_Renamings:: 220* Pragma Partition_Elaboration_Policy:: 221* Pragma Part_Of:: 222* Pragma Passive:: 223* Pragma Persistent_BSS:: 224* Pragma Polling:: 225* Pragma Post:: 226* Pragma Postcondition:: 227* Pragma Post_Class:: 228* Pragma Rename_Pragma:: 229* Pragma Pre:: 230* Pragma Precondition:: 231* Pragma Predicate:: 232* Pragma Predicate_Failure:: 233* Pragma Preelaborable_Initialization:: 234* Pragma Prefix_Exception_Messages:: 235* Pragma Pre_Class:: 236* Pragma Priority_Specific_Dispatching:: 237* Pragma Profile:: 238* Pragma Profile_Warnings:: 239* Pragma Propagate_Exceptions:: 240* Pragma Provide_Shift_Operators:: 241* Pragma Psect_Object:: 242* Pragma Pure_Function:: 243* Pragma Rational:: 244* Pragma Ravenscar:: 245* Pragma Refined_Depends:: 246* Pragma Refined_Global:: 247* Pragma Refined_Post:: 248* Pragma Refined_State:: 249* Pragma Relative_Deadline:: 250* Pragma Remote_Access_Type:: 251* Pragma Restricted_Run_Time:: 252* Pragma Restriction_Warnings:: 253* Pragma Reviewable:: 254* Pragma Secondary_Stack_Size:: 255* Pragma Share_Generic:: 256* Pragma Shared:: 257* Pragma Short_Circuit_And_Or:: 258* Pragma Short_Descriptors:: 259* Pragma Simple_Storage_Pool_Type:: 260* Pragma Source_File_Name:: 261* Pragma Source_File_Name_Project:: 262* Pragma Source_Reference:: 263* Pragma SPARK_Mode:: 264* Pragma Static_Elaboration_Desired:: 265* Pragma Stream_Convert:: 266* Pragma Style_Checks:: 267* Pragma Subtitle:: 268* Pragma Suppress:: 269* Pragma Suppress_All:: 270* Pragma Suppress_Debug_Info:: 271* Pragma Suppress_Exception_Locations:: 272* Pragma Suppress_Initialization:: 273* Pragma Task_Name:: 274* Pragma Task_Storage:: 275* Pragma Test_Case:: 276* Pragma Thread_Local_Storage:: 277* Pragma Time_Slice:: 278* Pragma Title:: 279* Pragma Type_Invariant:: 280* Pragma Type_Invariant_Class:: 281* Pragma Unchecked_Union:: 282* Pragma Unevaluated_Use_Of_Old:: 283* Pragma Unimplemented_Unit:: 284* Pragma Universal_Aliasing:: 285* Pragma Universal_Data:: 286* Pragma Unmodified:: 287* Pragma Unreferenced:: 288* Pragma Unreferenced_Objects:: 289* Pragma Unreserve_All_Interrupts:: 290* Pragma Unsuppress:: 291* Pragma Use_VADS_Size:: 292* Pragma Unused:: 293* Pragma Validity_Checks:: 294* Pragma Volatile:: 295* Pragma Volatile_Full_Access:: 296* Pragma Volatile_Function:: 297* Pragma Warning_As_Error:: 298* Pragma Warnings:: 299* Pragma Weak_External:: 300* Pragma Wide_Character_Encoding:: 301 302Implementation Defined Aspects 303 304* Aspect Abstract_State:: 305* Aspect Annotate:: 306* Aspect Async_Readers:: 307* Aspect Async_Writers:: 308* Aspect Constant_After_Elaboration:: 309* Aspect Contract_Cases:: 310* Aspect Depends:: 311* Aspect Default_Initial_Condition:: 312* Aspect Dimension:: 313* Aspect Dimension_System:: 314* Aspect Disable_Controlled:: 315* Aspect Effective_Reads:: 316* Aspect Effective_Writes:: 317* Aspect Extensions_Visible:: 318* Aspect Favor_Top_Level:: 319* Aspect Ghost:: 320* Aspect Global:: 321* Aspect Initial_Condition:: 322* Aspect Initializes:: 323* Aspect Inline_Always:: 324* Aspect Invariant:: 325* Aspect Invariant'Class:: 326* Aspect Iterable:: 327* Aspect Linker_Section:: 328* Aspect Lock_Free:: 329* Aspect Max_Queue_Length:: 330* Aspect No_Elaboration_Code_All:: 331* Aspect No_Inline:: 332* Aspect No_Tagged_Streams:: 333* Aspect Object_Size:: 334* Aspect Obsolescent:: 335* Aspect Part_Of:: 336* Aspect Persistent_BSS:: 337* Aspect Predicate:: 338* Aspect Pure_Function:: 339* Aspect Refined_Depends:: 340* Aspect Refined_Global:: 341* Aspect Refined_Post:: 342* Aspect Refined_State:: 343* Aspect Remote_Access_Type:: 344* Aspect Secondary_Stack_Size:: 345* Aspect Scalar_Storage_Order:: 346* Aspect Shared:: 347* Aspect Simple_Storage_Pool:: 348* Aspect Simple_Storage_Pool_Type:: 349* Aspect SPARK_Mode:: 350* Aspect Suppress_Debug_Info:: 351* Aspect Suppress_Initialization:: 352* Aspect Test_Case:: 353* Aspect Thread_Local_Storage:: 354* Aspect Universal_Aliasing:: 355* Aspect Universal_Data:: 356* Aspect Unmodified:: 357* Aspect Unreferenced:: 358* Aspect Unreferenced_Objects:: 359* Aspect Value_Size:: 360* Aspect Volatile_Full_Access:: 361* Aspect Volatile_Function:: 362* Aspect Warnings:: 363 364Implementation Defined Attributes 365 366* Attribute Abort_Signal:: 367* Attribute Address_Size:: 368* Attribute Asm_Input:: 369* Attribute Asm_Output:: 370* Attribute Atomic_Always_Lock_Free:: 371* Attribute Bit:: 372* Attribute Bit_Position:: 373* Attribute Code_Address:: 374* Attribute Compiler_Version:: 375* Attribute Constrained:: 376* Attribute Default_Bit_Order:: 377* Attribute Default_Scalar_Storage_Order:: 378* Attribute Deref:: 379* Attribute Descriptor_Size:: 380* Attribute Elaborated:: 381* Attribute Elab_Body:: 382* Attribute Elab_Spec:: 383* Attribute Elab_Subp_Body:: 384* Attribute Emax:: 385* Attribute Enabled:: 386* Attribute Enum_Rep:: 387* Attribute Enum_Val:: 388* Attribute Epsilon:: 389* Attribute Fast_Math:: 390* Attribute Finalization_Size:: 391* Attribute Fixed_Value:: 392* Attribute From_Any:: 393* Attribute Has_Access_Values:: 394* Attribute Has_Discriminants:: 395* Attribute Img:: 396* Attribute Integer_Value:: 397* Attribute Invalid_Value:: 398* Attribute Iterable:: 399* Attribute Large:: 400* Attribute Library_Level:: 401* Attribute Lock_Free:: 402* Attribute Loop_Entry:: 403* Attribute Machine_Size:: 404* Attribute Mantissa:: 405* Attribute Maximum_Alignment:: 406* Attribute Mechanism_Code:: 407* Attribute Null_Parameter:: 408* Attribute Object_Size:: 409* Attribute Old:: 410* Attribute Passed_By_Reference:: 411* Attribute Pool_Address:: 412* Attribute Range_Length:: 413* Attribute Restriction_Set:: 414* Attribute Result:: 415* Attribute Safe_Emax:: 416* Attribute Safe_Large:: 417* Attribute Safe_Small:: 418* Attribute Scalar_Storage_Order:: 419* Attribute Simple_Storage_Pool:: 420* Attribute Small:: 421* Attribute Storage_Unit:: 422* Attribute Stub_Type:: 423* Attribute System_Allocator_Alignment:: 424* Attribute Target_Name:: 425* Attribute To_Address:: 426* Attribute To_Any:: 427* Attribute Type_Class:: 428* Attribute Type_Key:: 429* Attribute TypeCode:: 430* Attribute Unconstrained_Array:: 431* Attribute Universal_Literal_String:: 432* Attribute Unrestricted_Access:: 433* Attribute Update:: 434* Attribute Valid_Scalars:: 435* Attribute VADS_Size:: 436* Attribute Value_Size:: 437* Attribute Wchar_T_Size:: 438* Attribute Word_Size:: 439 440Standard and Implementation Defined Restrictions 441 442* Partition-Wide Restrictions:: 443* Program Unit Level Restrictions:: 444 445Partition-Wide Restrictions 446 447* Immediate_Reclamation:: 448* Max_Asynchronous_Select_Nesting:: 449* Max_Entry_Queue_Length:: 450* Max_Protected_Entries:: 451* Max_Select_Alternatives:: 452* Max_Storage_At_Blocking:: 453* Max_Task_Entries:: 454* Max_Tasks:: 455* No_Abort_Statements:: 456* No_Access_Parameter_Allocators:: 457* No_Access_Subprograms:: 458* No_Allocators:: 459* No_Anonymous_Allocators:: 460* No_Asynchronous_Control:: 461* No_Calendar:: 462* No_Coextensions:: 463* No_Default_Initialization:: 464* No_Delay:: 465* No_Dependence:: 466* No_Direct_Boolean_Operators:: 467* No_Dispatch:: 468* No_Dispatching_Calls:: 469* No_Dynamic_Attachment:: 470* No_Dynamic_Priorities:: 471* No_Entry_Calls_In_Elaboration_Code:: 472* No_Enumeration_Maps:: 473* No_Exception_Handlers:: 474* No_Exception_Propagation:: 475* No_Exception_Registration:: 476* No_Exceptions:: 477* No_Finalization:: 478* No_Fixed_Point:: 479* No_Floating_Point:: 480* No_Implicit_Conditionals:: 481* No_Implicit_Dynamic_Code:: 482* No_Implicit_Heap_Allocations:: 483* No_Implicit_Protected_Object_Allocations:: 484* No_Implicit_Task_Allocations:: 485* No_Initialize_Scalars:: 486* No_IO:: 487* No_Local_Allocators:: 488* No_Local_Protected_Objects:: 489* No_Local_Timing_Events:: 490* No_Long_Long_Integers:: 491* No_Multiple_Elaboration:: 492* No_Nested_Finalization:: 493* No_Protected_Type_Allocators:: 494* No_Protected_Types:: 495* No_Recursion:: 496* No_Reentrancy:: 497* No_Relative_Delay:: 498* No_Requeue_Statements:: 499* No_Secondary_Stack:: 500* No_Select_Statements:: 501* No_Specific_Termination_Handlers:: 502* No_Specification_of_Aspect:: 503* No_Standard_Allocators_After_Elaboration:: 504* No_Standard_Storage_Pools:: 505* No_Stream_Optimizations:: 506* No_Streams:: 507* No_Task_Allocators:: 508* No_Task_At_Interrupt_Priority:: 509* No_Task_Attributes_Package:: 510* No_Task_Hierarchy:: 511* No_Task_Termination:: 512* No_Tasking:: 513* No_Terminate_Alternatives:: 514* No_Unchecked_Access:: 515* No_Unchecked_Conversion:: 516* No_Unchecked_Deallocation:: 517* No_Use_Of_Entity:: 518* Pure_Barriers:: 519* Simple_Barriers:: 520* Static_Priorities:: 521* Static_Storage_Size:: 522 523Program Unit Level Restrictions 524 525* No_Elaboration_Code:: 526* No_Dynamic_Sized_Objects:: 527* No_Entry_Queue:: 528* No_Implementation_Aspect_Specifications:: 529* No_Implementation_Attributes:: 530* No_Implementation_Identifiers:: 531* No_Implementation_Pragmas:: 532* No_Implementation_Restrictions:: 533* No_Implementation_Units:: 534* No_Implicit_Aliasing:: 535* No_Implicit_Loops:: 536* No_Obsolescent_Features:: 537* No_Wide_Characters:: 538* Static_Dispatch_Tables:: 539* SPARK_05:: 540 541Implementation Advice 542 543* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 544* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 545* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 546* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 547* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 548* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 549* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 550* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 551* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 552* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 553* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 554* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 555* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 556* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 557* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 558* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 559* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 560* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 561* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 562* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 563* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 564* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 565* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 566* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 567* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 568* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 569* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 570* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 571* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 572* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 573* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 574* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 575* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 576* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 577* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 578* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 579* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 580* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 581* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 582* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 583* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 584* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 585* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 586* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 587* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 588* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 589* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 590* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 591* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 592* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 593* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 594* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 595* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 596* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 597* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 598* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 599* RM F(7); COBOL Support: RM F 7 COBOL Support. 600* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 601* RM G; Numerics: RM G Numerics. 602* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 603* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 604* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 605* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 606* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 607 608Intrinsic Subprograms 609 610* Intrinsic Operators:: 611* Compilation_ISO_Date:: 612* Compilation_Date:: 613* Compilation_Time:: 614* Enclosing_Entity:: 615* Exception_Information:: 616* Exception_Message:: 617* Exception_Name:: 618* File:: 619* Line:: 620* Shifts and Rotates:: 621* Source_Location:: 622 623Representation Clauses and Pragmas 624 625* Alignment Clauses:: 626* Size Clauses:: 627* Storage_Size Clauses:: 628* Size of Variant Record Objects:: 629* Biased Representation:: 630* Value_Size and Object_Size Clauses:: 631* Component_Size Clauses:: 632* Bit_Order Clauses:: 633* Effect of Bit_Order on Byte Ordering:: 634* Pragma Pack for Arrays:: 635* Pragma Pack for Records:: 636* Record Representation Clauses:: 637* Handling of Records with Holes:: 638* Enumeration Clauses:: 639* Address Clauses:: 640* Use of Address Clauses for Memory-Mapped I/O:: 641* Effect of Convention on Representation:: 642* Conventions and Anonymous Access Types:: 643* Determining the Representations chosen by GNAT:: 644 645The Implementation of Standard I/O 646 647* Standard I/O Packages:: 648* FORM Strings:: 649* Direct_IO:: 650* Sequential_IO:: 651* Text_IO:: 652* Wide_Text_IO:: 653* Wide_Wide_Text_IO:: 654* Stream_IO:: 655* Text Translation:: 656* Shared Files:: 657* Filenames encoding:: 658* File content encoding:: 659* Open Modes:: 660* Operations on C Streams:: 661* Interfacing to C Streams:: 662 663Text_IO 664 665* Stream Pointer Positioning:: 666* Reading and Writing Non-Regular Files:: 667* Get_Immediate:: 668* Treating Text_IO Files as Streams:: 669* Text_IO Extensions:: 670* Text_IO Facilities for Unbounded Strings:: 671 672Wide_Text_IO 673 674* Stream Pointer Positioning: Stream Pointer Positioning<2>. 675* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 676 677Wide_Wide_Text_IO 678 679* Stream Pointer Positioning: Stream Pointer Positioning<3>. 680* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 681 682The GNAT Library 683 684* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 685* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 686* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 687* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 688* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 689* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 690* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 691* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 692* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 693* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 694* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 695* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 696* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 697* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 698* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 699* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 700* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 701* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 702* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 703* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 704* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 705* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 706* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 707* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 708* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 709* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 710* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 711* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 712* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 713* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 714* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 715* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 716* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 717* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 718* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 719* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 720* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 721* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 722* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 723* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 724* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 725* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 726* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 727* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 728* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 729* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 730* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 731* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 732* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 733* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 734* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 735* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 736* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 737* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 738* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 739* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 740* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 741* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 742* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 743* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 744* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 745* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 746* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 747* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 748* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 749* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 750* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 751* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 752* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 753* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 754* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 755* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 756* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 757* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 758* GNAT.Exceptions (g-expect.ads): GNAT Exceptions g-expect ads. 759* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 760* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 761* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 762* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 763* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 764* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 765* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 766* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 767* GNAT.IO (g-io.ads): GNAT IO g-io ads. 768* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 769* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 770* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 771* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 772* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 773* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 774* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 775* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 776* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 777* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 778* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 779* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 780* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 781* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 782* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 783* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 784* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 785* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 786* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 787* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 788* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 789* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 790* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 791* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 792* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 793* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 794* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 795* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 796* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 797* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 798* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 799* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 800* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 801* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 802* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 803* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 804* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 805* GNAT.Table (g-table.ads): GNAT Table g-table ads. 806* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 807* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 808* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 809* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 810* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 811* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 812* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 813* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 814* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 815* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 816* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 817* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 818* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 819* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 820* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 821* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 822* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 823* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 824* System.Assertions (s-assert.ads): System Assertions s-assert ads. 825* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 826* System.Memory (s-memory.ads): System Memory s-memory ads. 827* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 828* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 829* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 830* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 831* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 832* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 833* System.Rident (s-rident.ads): System Rident s-rident ads. 834* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 835* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 836* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 837* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 838 839Interfacing to Other Languages 840 841* Interfacing to C:: 842* Interfacing to C++:: 843* Interfacing to COBOL:: 844* Interfacing to Fortran:: 845* Interfacing to non-GNAT Ada code:: 846 847Implementation of Specific Ada Features 848 849* Machine Code Insertions:: 850* GNAT Implementation of Tasking:: 851* GNAT Implementation of Shared Passive Packages:: 852* Code Generation for Array Aggregates:: 853* The Size of Discriminated Records with Default Discriminants:: 854* Strict Conformance to the Ada Reference Manual:: 855 856GNAT Implementation of Tasking 857 858* Mapping Ada Tasks onto the Underlying Kernel Threads:: 859* Ensuring Compliance with the Real-Time Annex:: 860* Support for Locking Policies:: 861 862Code Generation for Array Aggregates 863 864* Static constant aggregates with static bounds:: 865* Constant aggregates with unconstrained nominal types:: 866* Aggregates with static bounds:: 867* Aggregates with nonstatic bounds:: 868* Aggregates in assignment statements:: 869 870Obsolescent Features 871 872* pragma No_Run_Time:: 873* pragma Ravenscar:: 874* pragma Restricted_Run_Time:: 875* pragma Task_Info:: 876* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 877 878Compatibility and Porting Guide 879 880* Writing Portable Fixed-Point Declarations:: 881* Compatibility with Ada 83:: 882* Compatibility between Ada 95 and Ada 2005:: 883* Implementation-dependent characteristics:: 884* Compatibility with Other Ada Systems:: 885* Representation Clauses:: 886* Compatibility with HP Ada 83:: 887 888Compatibility with Ada 83 889 890* Legal Ada 83 programs that are illegal in Ada 95:: 891* More deterministic semantics:: 892* Changed semantics:: 893* Other language compatibility issues:: 894 895Implementation-dependent characteristics 896 897* Implementation-defined pragmas:: 898* Implementation-defined attributes:: 899* Libraries:: 900* Elaboration order:: 901* Target-specific aspects:: 902 903@end detailmenu 904@end menu 905 906@node About This Guide,Implementation Defined Pragmas,Top,Top 907@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} 908@chapter About This Guide 909 910 911 912This manual contains useful information in writing programs using the 913GNAT compiler. It includes information on implementation dependent 914characteristics of GNAT, including all the information required by 915Annex M of the Ada language standard. 916 917GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 918invoked in Ada 83 compatibility mode. 919By default, GNAT assumes Ada 2012, 920but you can override with a compiler switch 921to explicitly specify the language version. 922(Please refer to the @emph{GNAT User's Guide} for details on these switches.) 923Throughout this manual, references to 'Ada' without a year suffix 924apply to all the Ada versions of the language. 925 926Ada is designed to be highly portable. 927In general, a program will have the same effect even when compiled by 928different compilers on different platforms. 929However, since Ada is designed to be used in a 930wide variety of applications, it also contains a number of system 931dependent features to be used in interfacing to the external world. 932 933@geindex Implementation-dependent features 934 935@geindex Portability 936 937Note: Any program that makes use of implementation-dependent features 938may be non-portable. You should follow good programming practice and 939isolate and clearly document any sections of your program that make use 940of these features in a non-portable manner. 941 942@menu 943* What This Reference Manual Contains:: 944* Conventions:: 945* Related Information:: 946 947@end menu 948 949@node What This Reference Manual Contains,Conventions,,About This Guide 950@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 951@section What This Reference Manual Contains 952 953 954This reference manual contains the following chapters: 955 956 957@itemize * 958 959@item 960@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 961pragmas, which can be used to extend and enhance the functionality of the 962compiler. 963 964@item 965@ref{8,,Implementation Defined Attributes}, lists GNAT 966implementation-dependent attributes, which can be used to extend and 967enhance the functionality of the compiler. 968 969@item 970@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 971implementation-dependent restrictions, which can be used to extend and 972enhance the functionality of the compiler. 973 974@item 975@ref{a,,Implementation Advice}, provides information on generally 976desirable behavior which are not requirements that all compilers must 977follow since it cannot be provided on all systems, or which may be 978undesirable on some systems. 979 980@item 981@ref{b,,Implementation Defined Characteristics}, provides a guide to 982minimizing implementation dependent features. 983 984@item 985@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 986implemented by GNAT, and how they can be imported into user 987application programs. 988 989@item 990@ref{d,,Representation Clauses and Pragmas}, describes in detail the 991way that GNAT represents data, and in particular the exact set 992of representation clauses and pragmas that is accepted. 993 994@item 995@ref{e,,Standard Library Routines}, provides a listing of packages and a 996brief description of the functionality that is provided by Ada's 997extensive set of standard library routines as implemented by GNAT. 998 999@item 1000@ref{f,,The Implementation of Standard I/O}, details how the GNAT 1001implementation of the input-output facilities. 1002 1003@item 1004@ref{10,,The GNAT Library}, is a catalog of packages that complement 1005the Ada predefined library. 1006 1007@item 1008@ref{11,,Interfacing to Other Languages}, describes how programs 1009written in Ada using GNAT can be interfaced to other programming 1010languages. 1011 1012@item 1013@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 1014of the specialized needs annexes. 1015 1016@item 1017@ref{13,,Implementation of Specific Ada Features}, discusses issues related 1018to GNAT's implementation of machine code insertions, tasking, and several 1019other features. 1020 1021@item 1022@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1023GNAT implementation of the Ada 2012 language standard. 1024 1025@item 1026@ref{15,,Obsolescent Features} documents implementation dependent features, 1027including pragmas and attributes, which are considered obsolescent, since 1028there are other preferred ways of achieving the same results. These 1029obsolescent forms are retained for backwards compatibility. 1030 1031@item 1032@ref{16,,Compatibility and Porting Guide} presents some guidelines for 1033developing portable Ada code, describes the compatibility issues that 1034may arise between GNAT and other Ada compilation systems (including those 1035for Ada 83), and shows how GNAT can expedite porting applications 1036developed in other Ada environments. 1037 1038@item 1039@ref{1,,GNU Free Documentation License} contains the license for this document. 1040@end itemize 1041 1042@geindex Ada 95 Language Reference Manual 1043 1044@geindex Ada 2005 Language Reference Manual 1045 1046This reference manual assumes a basic familiarity with the Ada 95 language, as 1047described in the 1048@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1049It does not require knowledge of the new features introduced by Ada 2005 or 1050Ada 2012. 1051All three reference manuals are included in the GNAT documentation 1052package. 1053 1054@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1055@anchor{gnat_rm/about_this_guide conventions}@anchor{17} 1056@section Conventions 1057 1058 1059@geindex Conventions 1060@geindex typographical 1061 1062@geindex Typographical conventions 1063 1064Following are examples of the typographical and graphic conventions used 1065in this guide: 1066 1067 1068@itemize * 1069 1070@item 1071@code{Functions}, @code{utility program names}, @code{standard names}, 1072and @code{classes}. 1073 1074@item 1075@code{Option flags} 1076 1077@item 1078@code{File names} 1079 1080@item 1081@code{Variables} 1082 1083@item 1084@emph{Emphasis} 1085 1086@item 1087[optional information or parameters] 1088 1089@item 1090Examples are described by text 1091 1092@example 1093and then shown this way. 1094@end example 1095 1096@item 1097Commands that are entered by the user are shown as preceded by a prompt string 1098comprising the @code{$} character followed by a space. 1099@end itemize 1100 1101@node Related Information,,Conventions,About This Guide 1102@anchor{gnat_rm/about_this_guide related-information}@anchor{18} 1103@section Related Information 1104 1105 1106See the following documents for further information on GNAT: 1107 1108 1109@itemize * 1110 1111@item 1112@cite{GNAT User's Guide for Native Platforms}, 1113which provides information on how to use the 1114GNAT development environment. 1115 1116@item 1117@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1118 1119@item 1120@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1121of the Ada 95 standard. The annotations describe 1122detailed aspects of the design decision, and in particular contain useful 1123sections on Ada 83 compatibility. 1124 1125@item 1126@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1127 1128@item 1129@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1130of the Ada 2005 standard. The annotations describe 1131detailed aspects of the design decision. 1132 1133@item 1134@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1135 1136@item 1137@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1138which contains specific information on compatibility between GNAT and 1139DEC Ada 83 systems. 1140 1141@item 1142@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1143describes in detail the pragmas and attributes provided by the DEC Ada 83 1144compiler system. 1145@end itemize 1146 1147@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1148@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} 1149@chapter Implementation Defined Pragmas 1150 1151 1152Ada defines a set of pragmas that can be used to supply additional 1153information to the compiler. These language defined pragmas are 1154implemented in GNAT and work as described in the Ada Reference Manual. 1155 1156In addition, Ada allows implementations to define additional pragmas 1157whose meaning is defined by the implementation. GNAT provides a number 1158of these implementation-defined pragmas, which can be used to extend 1159and enhance the functionality of the compiler. This section of the GNAT 1160Reference Manual describes these additional pragmas. 1161 1162Note that any program using these pragmas might not be portable to other 1163compilers (although GNAT implements this set of pragmas on all 1164platforms). Therefore if portability to other compilers is an important 1165consideration, the use of these pragmas should be minimized. 1166 1167@menu 1168* Pragma Abort_Defer:: 1169* Pragma Abstract_State:: 1170* Pragma Ada_83:: 1171* Pragma Ada_95:: 1172* Pragma Ada_05:: 1173* Pragma Ada_2005:: 1174* Pragma Ada_12:: 1175* Pragma Ada_2012:: 1176* Pragma Allow_Integer_Address:: 1177* Pragma Annotate:: 1178* Pragma Assert:: 1179* Pragma Assert_And_Cut:: 1180* Pragma Assertion_Policy:: 1181* Pragma Assume:: 1182* Pragma Assume_No_Invalid_Values:: 1183* Pragma Async_Readers:: 1184* Pragma Async_Writers:: 1185* Pragma Attribute_Definition:: 1186* Pragma C_Pass_By_Copy:: 1187* Pragma Check:: 1188* Pragma Check_Float_Overflow:: 1189* Pragma Check_Name:: 1190* Pragma Check_Policy:: 1191* Pragma Comment:: 1192* Pragma Common_Object:: 1193* Pragma Compile_Time_Error:: 1194* Pragma Compile_Time_Warning:: 1195* Pragma Compiler_Unit:: 1196* Pragma Compiler_Unit_Warning:: 1197* Pragma Complete_Representation:: 1198* Pragma Complex_Representation:: 1199* Pragma Component_Alignment:: 1200* Pragma Constant_After_Elaboration:: 1201* Pragma Contract_Cases:: 1202* Pragma Convention_Identifier:: 1203* Pragma CPP_Class:: 1204* Pragma CPP_Constructor:: 1205* Pragma CPP_Virtual:: 1206* Pragma CPP_Vtable:: 1207* Pragma CPU:: 1208* Pragma Deadline_Floor:: 1209* Pragma Default_Initial_Condition:: 1210* Pragma Debug:: 1211* Pragma Debug_Policy:: 1212* Pragma Default_Scalar_Storage_Order:: 1213* Pragma Default_Storage_Pool:: 1214* Pragma Depends:: 1215* Pragma Detect_Blocking:: 1216* Pragma Disable_Atomic_Synchronization:: 1217* Pragma Dispatching_Domain:: 1218* Pragma Effective_Reads:: 1219* Pragma Effective_Writes:: 1220* Pragma Elaboration_Checks:: 1221* Pragma Eliminate:: 1222* Pragma Enable_Atomic_Synchronization:: 1223* Pragma Export_Function:: 1224* Pragma Export_Object:: 1225* Pragma Export_Procedure:: 1226* Pragma Export_Value:: 1227* Pragma Export_Valued_Procedure:: 1228* Pragma Extend_System:: 1229* Pragma Extensions_Allowed:: 1230* Pragma Extensions_Visible:: 1231* Pragma External:: 1232* Pragma External_Name_Casing:: 1233* Pragma Fast_Math:: 1234* Pragma Favor_Top_Level:: 1235* Pragma Finalize_Storage_Only:: 1236* Pragma Float_Representation:: 1237* Pragma Ghost:: 1238* Pragma Global:: 1239* Pragma Ident:: 1240* Pragma Ignore_Pragma:: 1241* Pragma Implementation_Defined:: 1242* Pragma Implemented:: 1243* Pragma Implicit_Packing:: 1244* Pragma Import_Function:: 1245* Pragma Import_Object:: 1246* Pragma Import_Procedure:: 1247* Pragma Import_Valued_Procedure:: 1248* Pragma Independent:: 1249* Pragma Independent_Components:: 1250* Pragma Initial_Condition:: 1251* Pragma Initialize_Scalars:: 1252* Pragma Initializes:: 1253* Pragma Inline_Always:: 1254* Pragma Inline_Generic:: 1255* Pragma Interface:: 1256* Pragma Interface_Name:: 1257* Pragma Interrupt_Handler:: 1258* Pragma Interrupt_State:: 1259* Pragma Invariant:: 1260* Pragma Keep_Names:: 1261* Pragma License:: 1262* Pragma Link_With:: 1263* Pragma Linker_Alias:: 1264* Pragma Linker_Constructor:: 1265* Pragma Linker_Destructor:: 1266* Pragma Linker_Section:: 1267* Pragma Lock_Free:: 1268* Pragma Loop_Invariant:: 1269* Pragma Loop_Optimize:: 1270* Pragma Loop_Variant:: 1271* Pragma Machine_Attribute:: 1272* Pragma Main:: 1273* Pragma Main_Storage:: 1274* Pragma Max_Queue_Length:: 1275* Pragma No_Body:: 1276* Pragma No_Component_Reordering:: 1277* Pragma No_Elaboration_Code_All:: 1278* Pragma No_Heap_Finalization:: 1279* Pragma No_Inline:: 1280* Pragma No_Return:: 1281* Pragma No_Run_Time:: 1282* Pragma No_Strict_Aliasing:: 1283* Pragma No_Tagged_Streams:: 1284* Pragma Normalize_Scalars:: 1285* Pragma Obsolescent:: 1286* Pragma Optimize_Alignment:: 1287* Pragma Ordered:: 1288* Pragma Overflow_Mode:: 1289* Pragma Overriding_Renamings:: 1290* Pragma Partition_Elaboration_Policy:: 1291* Pragma Part_Of:: 1292* Pragma Passive:: 1293* Pragma Persistent_BSS:: 1294* Pragma Polling:: 1295* Pragma Post:: 1296* Pragma Postcondition:: 1297* Pragma Post_Class:: 1298* Pragma Rename_Pragma:: 1299* Pragma Pre:: 1300* Pragma Precondition:: 1301* Pragma Predicate:: 1302* Pragma Predicate_Failure:: 1303* Pragma Preelaborable_Initialization:: 1304* Pragma Prefix_Exception_Messages:: 1305* Pragma Pre_Class:: 1306* Pragma Priority_Specific_Dispatching:: 1307* Pragma Profile:: 1308* Pragma Profile_Warnings:: 1309* Pragma Propagate_Exceptions:: 1310* Pragma Provide_Shift_Operators:: 1311* Pragma Psect_Object:: 1312* Pragma Pure_Function:: 1313* Pragma Rational:: 1314* Pragma Ravenscar:: 1315* Pragma Refined_Depends:: 1316* Pragma Refined_Global:: 1317* Pragma Refined_Post:: 1318* Pragma Refined_State:: 1319* Pragma Relative_Deadline:: 1320* Pragma Remote_Access_Type:: 1321* Pragma Restricted_Run_Time:: 1322* Pragma Restriction_Warnings:: 1323* Pragma Reviewable:: 1324* Pragma Secondary_Stack_Size:: 1325* Pragma Share_Generic:: 1326* Pragma Shared:: 1327* Pragma Short_Circuit_And_Or:: 1328* Pragma Short_Descriptors:: 1329* Pragma Simple_Storage_Pool_Type:: 1330* Pragma Source_File_Name:: 1331* Pragma Source_File_Name_Project:: 1332* Pragma Source_Reference:: 1333* Pragma SPARK_Mode:: 1334* Pragma Static_Elaboration_Desired:: 1335* Pragma Stream_Convert:: 1336* Pragma Style_Checks:: 1337* Pragma Subtitle:: 1338* Pragma Suppress:: 1339* Pragma Suppress_All:: 1340* Pragma Suppress_Debug_Info:: 1341* Pragma Suppress_Exception_Locations:: 1342* Pragma Suppress_Initialization:: 1343* Pragma Task_Name:: 1344* Pragma Task_Storage:: 1345* Pragma Test_Case:: 1346* Pragma Thread_Local_Storage:: 1347* Pragma Time_Slice:: 1348* Pragma Title:: 1349* Pragma Type_Invariant:: 1350* Pragma Type_Invariant_Class:: 1351* Pragma Unchecked_Union:: 1352* Pragma Unevaluated_Use_Of_Old:: 1353* Pragma Unimplemented_Unit:: 1354* Pragma Universal_Aliasing:: 1355* Pragma Universal_Data:: 1356* Pragma Unmodified:: 1357* Pragma Unreferenced:: 1358* Pragma Unreferenced_Objects:: 1359* Pragma Unreserve_All_Interrupts:: 1360* Pragma Unsuppress:: 1361* Pragma Use_VADS_Size:: 1362* Pragma Unused:: 1363* Pragma Validity_Checks:: 1364* Pragma Volatile:: 1365* Pragma Volatile_Full_Access:: 1366* Pragma Volatile_Function:: 1367* Pragma Warning_As_Error:: 1368* Pragma Warnings:: 1369* Pragma Weak_External:: 1370* Pragma Wide_Character_Encoding:: 1371 1372@end menu 1373 1374@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1375@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b} 1376@section Pragma Abort_Defer 1377 1378 1379@geindex Deferring aborts 1380 1381Syntax: 1382 1383@example 1384pragma Abort_Defer; 1385@end example 1386 1387This pragma must appear at the start of the statement sequence of a 1388handled sequence of statements (right after the @code{begin}). It has 1389the effect of deferring aborts for the sequence of statements (but not 1390for the declarations or handlers, if any, associated with this statement 1391sequence). 1392 1393@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas 1394@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d} 1395@section Pragma Abstract_State 1396 1397 1398Syntax: 1399 1400@example 1401pragma Abstract_State (ABSTRACT_STATE_LIST); 1402 1403ABSTRACT_STATE_LIST ::= 1404 null 1405 | STATE_NAME_WITH_OPTIONS 1406 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1407 1408STATE_NAME_WITH_OPTIONS ::= 1409 STATE_NAME 1410 | (STATE_NAME with OPTION_LIST) 1411 1412OPTION_LIST ::= OPTION @{, OPTION@} 1413 1414OPTION ::= 1415 SIMPLE_OPTION 1416 | NAME_VALUE_OPTION 1417 1418SIMPLE_OPTION ::= Ghost | Synchronous 1419 1420NAME_VALUE_OPTION ::= 1421 Part_Of => ABSTRACT_STATE 1422 | External [=> EXTERNAL_PROPERTY_LIST] 1423 1424EXTERNAL_PROPERTY_LIST ::= 1425 EXTERNAL_PROPERTY 1426 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1427 1428EXTERNAL_PROPERTY ::= 1429 Async_Readers [=> boolean_EXPRESSION] 1430 | Async_Writers [=> boolean_EXPRESSION] 1431 | Effective_Reads [=> boolean_EXPRESSION] 1432 | Effective_Writes [=> boolean_EXPRESSION] 1433 others => boolean_EXPRESSION 1434 1435STATE_NAME ::= defining_identifier 1436 1437ABSTRACT_STATE ::= name 1438@end example 1439 1440For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in 1441the SPARK 2014 Reference Manual, section 7.1.4. 1442 1443@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas 1444@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1e} 1445@section Pragma Ada_83 1446 1447 1448Syntax: 1449 1450@example 1451pragma Ada_83; 1452@end example 1453 1454A configuration pragma that establishes Ada 83 mode for the unit to 1455which it applies, regardless of the mode set by the command line 1456switches. In Ada 83 mode, GNAT attempts to be as compatible with 1457the syntax and semantics of Ada 83, as defined in the original Ada 145883 Reference Manual as possible. In particular, the keywords added by Ada 95 1459and Ada 2005 are not recognized, optional package bodies are allowed, 1460and generics may name types with unknown discriminants without using 1461the @code{(<>)} notation. In addition, some but not all of the additional 1462restrictions of Ada 83 are enforced. 1463 1464Ada 83 mode is intended for two purposes. Firstly, it allows existing 1465Ada 83 code to be compiled and adapted to GNAT with less effort. 1466Secondly, it aids in keeping code backwards compatible with Ada 83. 1467However, there is no guarantee that code that is processed correctly 1468by GNAT in Ada 83 mode will in fact compile and execute with an Ada 146983 compiler, since GNAT does not enforce all the additional checks 1470required by Ada 83. 1471 1472@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1473@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{1f} 1474@section Pragma Ada_95 1475 1476 1477Syntax: 1478 1479@example 1480pragma Ada_95; 1481@end example 1482 1483A configuration pragma that establishes Ada 95 mode for the unit to which 1484it applies, regardless of the mode set by the command line switches. 1485This mode is set automatically for the @code{Ada} and @code{System} 1486packages and their children, so you need not specify it in these 1487contexts. This pragma is useful when writing a reusable component that 1488itself uses Ada 95 features, but which is intended to be usable from 1489either Ada 83 or Ada 95 programs. 1490 1491@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1492@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{20} 1493@section Pragma Ada_05 1494 1495 1496Syntax: 1497 1498@example 1499pragma Ada_05; 1500pragma Ada_05 (local_NAME); 1501@end example 1502 1503A configuration pragma that establishes Ada 2005 mode for the unit to which 1504it applies, regardless of the mode set by the command line switches. 1505This pragma is useful when writing a reusable component that 1506itself uses Ada 2005 features, but which is intended to be usable from 1507either Ada 83 or Ada 95 programs. 1508 1509The one argument form (which is not a configuration pragma) 1510is used for managing the transition from 1511Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1512as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1513mode will generate a warning. In addition, in Ada_83 or Ada_95 1514mode, a preference rule is established which does not choose 1515such an entity unless it is unambiguously specified. This avoids 1516extra subprograms marked this way from generating ambiguities in 1517otherwise legal pre-Ada_2005 programs. The one argument form is 1518intended for exclusive use in the GNAT run-time library. 1519 1520@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1521@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{21} 1522@section Pragma Ada_2005 1523 1524 1525Syntax: 1526 1527@example 1528pragma Ada_2005; 1529@end example 1530 1531This configuration pragma is a synonym for pragma Ada_05 and has the 1532same syntax and effect. 1533 1534@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1535@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{22} 1536@section Pragma Ada_12 1537 1538 1539Syntax: 1540 1541@example 1542pragma Ada_12; 1543pragma Ada_12 (local_NAME); 1544@end example 1545 1546A configuration pragma that establishes Ada 2012 mode for the unit to which 1547it applies, regardless of the mode set by the command line switches. 1548This mode is set automatically for the @code{Ada} and @code{System} 1549packages and their children, so you need not specify it in these 1550contexts. This pragma is useful when writing a reusable component that 1551itself uses Ada 2012 features, but which is intended to be usable from 1552Ada 83, Ada 95, or Ada 2005 programs. 1553 1554The one argument form, which is not a configuration pragma, 1555is used for managing the transition from Ada 15562005 to Ada 2012 in the run-time library. If an entity is marked 1557as Ada_2012 only, then referencing the entity in any pre-Ada_2012 1558mode will generate a warning. In addition, in any pre-Ada_2012 1559mode, a preference rule is established which does not choose 1560such an entity unless it is unambiguously specified. This avoids 1561extra subprograms marked this way from generating ambiguities in 1562otherwise legal pre-Ada_2012 programs. The one argument form is 1563intended for exclusive use in the GNAT run-time library. 1564 1565@node Pragma Ada_2012,Pragma Allow_Integer_Address,Pragma Ada_12,Implementation Defined Pragmas 1566@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{23} 1567@section Pragma Ada_2012 1568 1569 1570Syntax: 1571 1572@example 1573pragma Ada_2012; 1574@end example 1575 1576This configuration pragma is a synonym for pragma Ada_12 and has the 1577same syntax and effect. 1578 1579@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Ada_2012,Implementation Defined Pragmas 1580@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{24} 1581@section Pragma Allow_Integer_Address 1582 1583 1584Syntax: 1585 1586@example 1587pragma Allow_Integer_Address; 1588@end example 1589 1590In almost all versions of GNAT, @code{System.Address} is a private 1591type in accordance with the implementation advice in the RM. This 1592means that integer values, 1593in particular integer literals, are not allowed as address values. 1594If the configuration pragma 1595@code{Allow_Integer_Address} is given, then integer expressions may 1596be used anywhere a value of type @code{System.Address} is required. 1597The effect is to introduce an implicit unchecked conversion from the 1598integer value to type @code{System.Address}. The reverse case of using 1599an address where an integer type is required is handled analogously. 1600The following example compiles without errors: 1601 1602@example 1603pragma Allow_Integer_Address; 1604with System; use System; 1605package AddrAsInt is 1606 X : Integer; 1607 Y : Integer; 1608 for X'Address use 16#1240#; 1609 for Y use at 16#3230#; 1610 m : Address := 16#4000#; 1611 n : constant Address := 4000; 1612 p : constant Address := Address (X + Y); 1613 v : Integer := y'Address; 1614 w : constant Integer := Integer (Y'Address); 1615 type R is new integer; 1616 RR : R := 1000; 1617 Z : Integer; 1618 for Z'Address use RR; 1619end AddrAsInt; 1620@end example 1621 1622Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} 1623is not a private type. In implementations of @code{GNAT} where 1624System.Address is a visible integer type, 1625this pragma serves no purpose but is ignored 1626rather than rejected to allow common sets of sources to be used 1627in the two situations. 1628 1629@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1630@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{25}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{26} 1631@section Pragma Annotate 1632 1633 1634Syntax: 1635 1636@example 1637pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1638 1639ARG ::= NAME | EXPRESSION 1640@end example 1641 1642This pragma is used to annotate programs. IDENTIFIER identifies 1643the type of annotation. GNAT verifies that it is an identifier, but does 1644not otherwise analyze it. The second optional identifier is also left 1645unanalyzed, and by convention is used to control the action of the tool to 1646which the annotation is addressed. The remaining ARG arguments 1647can be either string literals or more generally expressions. 1648String literals are assumed to be either of type 1649@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1650depending on the character literals they contain. 1651All other kinds of arguments are analyzed as expressions, and must be 1652unambiguous. The last argument if present must have the identifier 1653@code{Entity} and GNAT verifies that a local name is given. 1654 1655The analyzed pragma is retained in the tree, but not otherwise processed 1656by any part of the GNAT compiler, except to generate corresponding note 1657lines in the generated ALI file. For the format of these note lines, see 1658the compiler source file lib-writ.ads. This pragma is intended for use by 1659external tools, including ASIS. The use of pragma Annotate does not 1660affect the compilation process in any way. This pragma may be used as 1661a configuration pragma. 1662 1663@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1664@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{27} 1665@section Pragma Assert 1666 1667 1668Syntax: 1669 1670@example 1671pragma Assert ( 1672 boolean_EXPRESSION 1673 [, string_EXPRESSION]); 1674@end example 1675 1676The effect of this pragma depends on whether the corresponding command 1677line switch is set to activate assertions. The pragma expands into code 1678equivalent to the following: 1679 1680@example 1681if assertions-enabled then 1682 if not boolean_EXPRESSION then 1683 System.Assertions.Raise_Assert_Failure 1684 (string_EXPRESSION); 1685 end if; 1686end if; 1687@end example 1688 1689The string argument, if given, is the message that will be associated 1690with the exception occurrence if the exception is raised. If no second 1691argument is given, the default message is @code{file}:@code{nnn}, 1692where @code{file} is the name of the source file containing the assert, 1693and @code{nnn} is the line number of the assert. 1694 1695Note that, as with the @code{if} statement to which it is equivalent, the 1696type of the expression is either @code{Standard.Boolean}, or any type derived 1697from this standard type. 1698 1699Assert checks can be either checked or ignored. By default they are ignored. 1700They will be checked if either the command line switch @emph{-gnata} is 1701used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1702to enable @code{Assert_Checks}. 1703 1704If assertions are ignored, then there 1705is no run-time effect (and in particular, any side effects from the 1706expression will not occur at run time). (The expression is still 1707analyzed at compile time, and may cause types to be frozen if they are 1708mentioned here for the first time). 1709 1710If assertions are checked, then the given expression is tested, and if 1711it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1712which results in the raising of @code{Assert_Failure} with the given message. 1713 1714You should generally avoid side effects in the expression arguments of 1715this pragma, because these side effects will turn on and off with the 1716setting of the assertions mode, resulting in assertions that have an 1717effect on the program. However, the expressions are analyzed for 1718semantic correctness whether or not assertions are enabled, so turning 1719assertions on and off cannot affect the legality of a program. 1720 1721Note that the implementation defined policy @code{DISABLE}, given in a 1722pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1723 1724Note: this is a standard language-defined pragma in versions 1725of Ada from 2005 on. In GNAT, it is implemented in all versions 1726of Ada, and the DISABLE policy is an implementation-defined 1727addition. 1728 1729@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1730@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{28} 1731@section Pragma Assert_And_Cut 1732 1733 1734Syntax: 1735 1736@example 1737pragma Assert_And_Cut ( 1738 boolean_EXPRESSION 1739 [, string_EXPRESSION]); 1740@end example 1741 1742The effect of this pragma is identical to that of pragma @code{Assert}, 1743except that in an @code{Assertion_Policy} pragma, the identifier 1744@code{Assert_And_Cut} is used to control whether it is ignored or checked 1745(or disabled). 1746 1747The intention is that this be used within a subprogram when the 1748given test expresion sums up all the work done so far in the 1749subprogram, so that the rest of the subprogram can be verified 1750(informally or formally) using only the entry preconditions, 1751and the expression in this pragma. This allows dividing up 1752a subprogram into sections for the purposes of testing or 1753formal verification. The pragma also serves as useful 1754documentation. 1755 1756@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1757@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{29} 1758@section Pragma Assertion_Policy 1759 1760 1761Syntax: 1762 1763@example 1764pragma Assertion_Policy (CHECK | DISABLE | IGNORE); 1765 1766pragma Assertion_Policy ( 1767 ASSERTION_KIND => POLICY_IDENTIFIER 1768 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1769 1770ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1771 1772RM_ASSERTION_KIND ::= Assert | 1773 Static_Predicate | 1774 Dynamic_Predicate | 1775 Pre | 1776 Pre'Class | 1777 Post | 1778 Post'Class | 1779 Type_Invariant | 1780 Type_Invariant'Class 1781 1782ID_ASSERTION_KIND ::= Assertions | 1783 Assert_And_Cut | 1784 Assume | 1785 Contract_Cases | 1786 Debug | 1787 Ghost | 1788 Invariant | 1789 Invariant'Class | 1790 Loop_Invariant | 1791 Loop_Variant | 1792 Postcondition | 1793 Precondition | 1794 Predicate | 1795 Refined_Post | 1796 Statement_Assertions 1797 1798POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 1799@end example 1800 1801This is a standard Ada 2012 pragma that is available as an 1802implementation-defined pragma in earlier versions of Ada. 1803The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1804the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1805are implementation defined additions recognized by the GNAT compiler. 1806 1807The pragma applies in both cases to pragmas and aspects with matching 1808names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 1809applies to both the @code{Precondition} pragma 1810and the aspect @code{Precondition}. Note that the identifiers for 1811pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 1812Pre_Class and Post_Class), since these pragmas are intended to be 1813identical to the corresponding aspects). 1814 1815If the policy is @code{CHECK}, then assertions are enabled, i.e. 1816the corresponding pragma or aspect is activated. 1817If the policy is @code{IGNORE}, then assertions are ignored, i.e. 1818the corresponding pragma or aspect is deactivated. 1819This pragma overrides the effect of the @emph{-gnata} switch on the 1820command line. 1821If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, 1822however, if the @emph{-gnatp} switch is specified all assertions are ignored. 1823 1824The implementation defined policy @code{DISABLE} is like 1825@code{IGNORE} except that it completely disables semantic 1826checking of the corresponding pragma or aspect. This is 1827useful when the pragma or aspect argument references subprograms 1828in a with'ed package which is replaced by a dummy package 1829for the final build. 1830 1831The implementation defined assertion kind @code{Assertions} applies to all 1832assertion kinds. The form with no assertion kind given implies this 1833choice, so it applies to all assertion kinds (RM defined, and 1834implementation defined). 1835 1836The implementation defined assertion kind @code{Statement_Assertions} 1837applies to @code{Assert}, @code{Assert_And_Cut}, 1838@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 1839 1840@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 1841@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2a} 1842@section Pragma Assume 1843 1844 1845Syntax: 1846 1847@example 1848pragma Assume ( 1849 boolean_EXPRESSION 1850 [, string_EXPRESSION]); 1851@end example 1852 1853The effect of this pragma is identical to that of pragma @code{Assert}, 1854except that in an @code{Assertion_Policy} pragma, the identifier 1855@code{Assume} is used to control whether it is ignored or checked 1856(or disabled). 1857 1858The intention is that this be used for assumptions about the 1859external environment. So you cannot expect to verify formally 1860or informally that the condition is met, this must be 1861established by examining things outside the program itself. 1862For example, we may have code that depends on the size of 1863@code{Long_Long_Integer} being at least 64. So we could write: 1864 1865@example 1866pragma Assume (Long_Long_Integer'Size >= 64); 1867@end example 1868 1869This assumption cannot be proved from the program itself, 1870but it acts as a useful run-time check that the assumption 1871is met, and documents the need to ensure that it is met by 1872reference to information outside the program. 1873 1874@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 1875@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2b} 1876@section Pragma Assume_No_Invalid_Values 1877 1878 1879@geindex Invalid representations 1880 1881@geindex Invalid values 1882 1883Syntax: 1884 1885@example 1886pragma Assume_No_Invalid_Values (On | Off); 1887@end example 1888 1889This is a configuration pragma that controls the assumptions made by the 1890compiler about the occurrence of invalid representations (invalid values) 1891in the code. 1892 1893The default behavior (corresponding to an Off argument for this pragma), is 1894to assume that values may in general be invalid unless the compiler can 1895prove they are valid. Consider the following example: 1896 1897@example 1898V1 : Integer range 1 .. 10; 1899V2 : Integer range 11 .. 20; 1900... 1901for J in V2 .. V1 loop 1902 ... 1903end loop; 1904@end example 1905 1906if V1 and V2 have valid values, then the loop is known at compile 1907time not to execute since the lower bound must be greater than the 1908upper bound. However in default mode, no such assumption is made, 1909and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 1910is given, the compiler will assume that any occurrence of a variable 1911other than in an explicit @code{'Valid} test always has a valid 1912value, and the loop above will be optimized away. 1913 1914The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 1915you know your code is free of uninitialized variables and other 1916possible sources of invalid representations, and may result in 1917more efficient code. A program that accesses an invalid representation 1918with this pragma in effect is erroneous, so no guarantees can be made 1919about its behavior. 1920 1921It is peculiar though permissible to use this pragma in conjunction 1922with validity checking (-gnatVa). In such cases, accessing invalid 1923values will generally give an exception, though formally the program 1924is erroneous so there are no guarantees that this will always be the 1925case, and it is recommended that these two options not be used together. 1926 1927@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 1928@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2c}@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2d} 1929@section Pragma Async_Readers 1930 1931 1932Syntax: 1933 1934@example 1935pragma Asynch_Readers [ (boolean_EXPRESSION) ]; 1936@end example 1937 1938For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in 1939the SPARK 2014 Reference Manual, section 7.1.2. 1940 1941@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 1942@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{2e}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{2f} 1943@section Pragma Async_Writers 1944 1945 1946Syntax: 1947 1948@example 1949pragma Asynch_Writers [ (boolean_EXPRESSION) ]; 1950@end example 1951 1952For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in 1953the SPARK 2014 Reference Manual, section 7.1.2. 1954 1955@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 1956@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{30} 1957@section Pragma Attribute_Definition 1958 1959 1960Syntax: 1961 1962@example 1963pragma Attribute_Definition 1964 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 1965 [Entity =>] LOCAL_NAME, 1966 [Expression =>] EXPRESSION | NAME); 1967@end example 1968 1969If @code{Attribute} is a known attribute name, this pragma is equivalent to 1970the attribute definition clause: 1971 1972@example 1973for Entity'Attribute use Expression; 1974@end example 1975 1976If @code{Attribute} is not a recognized attribute name, the pragma is 1977ignored, and a warning is emitted. This allows source 1978code to be written that takes advantage of some new attribute, while remaining 1979compilable with earlier compilers. 1980 1981@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 1982@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{31} 1983@section Pragma C_Pass_By_Copy 1984 1985 1986@geindex Passing by copy 1987 1988Syntax: 1989 1990@example 1991pragma C_Pass_By_Copy 1992 ([Max_Size =>] static_integer_EXPRESSION); 1993@end example 1994 1995Normally the default mechanism for passing C convention records to C 1996convention subprograms is to pass them by reference, as suggested by RM 1997B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 1998this default, by requiring that record formal parameters be passed by 1999copy if all of the following conditions are met: 2000 2001 2002@itemize * 2003 2004@item 2005The size of the record type does not exceed the value specified for 2006@code{Max_Size}. 2007 2008@item 2009The record type has @code{Convention C}. 2010 2011@item 2012The formal parameter has this record type, and the subprogram has a 2013foreign (non-Ada) convention. 2014@end itemize 2015 2016If these conditions are met the argument is passed by copy; i.e., in a 2017manner consistent with what C expects if the corresponding formal in the 2018C prototype is a struct (rather than a pointer to a struct). 2019 2020You can also pass records by copy by specifying the convention 2021@code{C_Pass_By_Copy} for the record type, or by using the extended 2022@code{Import} and @code{Export} pragmas, which allow specification of 2023passing mechanisms on a parameter by parameter basis. 2024 2025@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 2026@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{32} 2027@section Pragma Check 2028 2029 2030@geindex Assertions 2031 2032@geindex Named assertions 2033 2034Syntax: 2035 2036@example 2037pragma Check ( 2038 [Name =>] CHECK_KIND, 2039 [Check =>] Boolean_EXPRESSION 2040 [, [Message =>] string_EXPRESSION] ); 2041 2042CHECK_KIND ::= IDENTIFIER | 2043 Pre'Class | 2044 Post'Class | 2045 Type_Invariant'Class | 2046 Invariant'Class 2047@end example 2048 2049This pragma is similar to the predefined pragma @code{Assert} except that an 2050extra identifier argument is present. In conjunction with pragma 2051@code{Check_Policy}, this can be used to define groups of assertions that can 2052be independently controlled. The identifier @code{Assertion} is special, it 2053refers to the normal set of pragma @code{Assert} statements. 2054 2055Checks introduced by this pragma are normally deactivated by default. They can 2056be activated either by the command line option @emph{-gnata}, which turns on 2057all checks, or individually controlled using pragma @code{Check_Policy}. 2058 2059The identifiers @code{Assertions} and @code{Statement_Assertions} are not 2060permitted as check kinds, since this would cause confusion with the use 2061of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 2062pragmas, where they are used to refer to sets of assertions. 2063 2064@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2065@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{33} 2066@section Pragma Check_Float_Overflow 2067 2068 2069@geindex Floating-point overflow 2070 2071Syntax: 2072 2073@example 2074pragma Check_Float_Overflow; 2075@end example 2076 2077In Ada, the predefined floating-point types (@code{Short_Float}, 2078@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 2079defined to be @emph{unconstrained}. This means that even though each 2080has a well-defined base range, an operation that delivers a result 2081outside this base range is not required to raise an exception. 2082This implementation permission accommodates the notion 2083of infinities in IEEE floating-point, and corresponds to the 2084efficient execution mode on most machines. GNAT will not raise 2085overflow exceptions on these machines; instead it will generate 2086infinities and NaN's as defined in the IEEE standard. 2087 2088Generating infinities, although efficient, is not always desirable. 2089Often the preferable approach is to check for overflow, even at the 2090(perhaps considerable) expense of run-time performance. 2091This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 2092range constraints -- and indeed such a subtype 2093can have the same base range as its base type. For example: 2094 2095@example 2096subtype My_Float is Float range Float'Range; 2097@end example 2098 2099Here @code{My_Float} has the same range as 2100@code{Float} but is constrained, so operations on 2101@code{My_Float} values will be checked for overflow 2102against this range. 2103 2104This style will achieve the desired goal, but 2105it is often more convenient to be able to simply use 2106the standard predefined floating-point types as long 2107as overflow checking could be guaranteed. 2108The @code{Check_Float_Overflow} 2109configuration pragma achieves this effect. If a unit is compiled 2110subject to this configuration pragma, then all operations 2111on predefined floating-point types including operations on 2112base types of these floating-point types will be treated as 2113though those types were constrained, and overflow checks 2114will be generated. The @code{Constraint_Error} 2115exception is raised if the result is out of range. 2116 2117This mode can also be set by use of the compiler 2118switch @emph{-gnateF}. 2119 2120@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2121@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{34} 2122@section Pragma Check_Name 2123 2124 2125@geindex Defining check names 2126 2127@geindex Check names 2128@geindex defining 2129 2130Syntax: 2131 2132@example 2133pragma Check_Name (check_name_IDENTIFIER); 2134@end example 2135 2136This is a configuration pragma that defines a new implementation 2137defined check name (unless IDENTIFIER matches one of the predefined 2138check names, in which case the pragma has no effect). Check names 2139are global to a partition, so if two or more configuration pragmas 2140are present in a partition mentioning the same name, only one new 2141check name is introduced. 2142 2143An implementation defined check name introduced with this pragma may 2144be used in only three contexts: @code{pragma Suppress}, 2145@code{pragma Unsuppress}, 2146and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 2147any of these three cases, the check name must be visible. A check 2148name is visible if it is in the configuration pragmas applying to 2149the current unit, or if it appears at the start of any unit that 2150is part of the dependency set of the current unit (e.g., units that 2151are mentioned in @code{with} clauses). 2152 2153Check names introduced by this pragma are subject to control by compiler 2154switches (in particular -gnatp) in the usual manner. 2155 2156@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2157@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{35} 2158@section Pragma Check_Policy 2159 2160 2161@geindex Controlling assertions 2162 2163@geindex Assertions 2164@geindex control 2165 2166@geindex Check pragma control 2167 2168@geindex Named assertions 2169 2170Syntax: 2171 2172@example 2173pragma Check_Policy 2174 ([Name =>] CHECK_KIND, 2175 [Policy =>] POLICY_IDENTIFIER); 2176 2177pragma Check_Policy ( 2178 CHECK_KIND => POLICY_IDENTIFIER 2179 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2180 2181ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2182 2183CHECK_KIND ::= IDENTIFIER | 2184 Pre'Class | 2185 Post'Class | 2186 Type_Invariant'Class | 2187 Invariant'Class 2188 2189The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2190avoids confusion between the two possible syntax forms for this pragma. 2191 2192POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2193@end example 2194 2195This pragma is used to set the checking policy for assertions (specified 2196by aspects or pragmas), the @code{Debug} pragma, or additional checks 2197to be checked using the @code{Check} pragma. It may appear either as 2198a configuration pragma, or within a declarative part of package. In the 2199latter case, it applies from the point where it appears to the end of 2200the declarative region (like pragma @code{Suppress}). 2201 2202The @code{Check_Policy} pragma is similar to the 2203predefined @code{Assertion_Policy} pragma, 2204and if the check kind corresponds to one of the assertion kinds that 2205are allowed by @code{Assertion_Policy}, then the effect is identical. 2206 2207If the first argument is Debug, then the policy applies to Debug pragmas, 2208disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 2209@code{IGNORE}, and allowing them to execute with normal semantics if 2210the policy is @code{ON} or @code{CHECK}. In addition if the policy is 2211@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 2212be totally ignored and not analyzed semantically. 2213 2214Finally the first argument may be some other identifier than the above 2215possibilities, in which case it controls a set of named assertions 2216that can be checked using pragma @code{Check}. For example, if the pragma: 2217 2218@example 2219pragma Check_Policy (Critical_Error, OFF); 2220@end example 2221 2222is given, then subsequent @code{Check} pragmas whose first argument is also 2223@code{Critical_Error} will be disabled. 2224 2225The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 2226to turn on corresponding checks. The default for a set of checks for which no 2227@code{Check_Policy} is given is @code{OFF} unless the compiler switch 2228@emph{-gnata} is given, which turns on all checks by default. 2229 2230The check policy settings @code{CHECK} and @code{IGNORE} are recognized 2231as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 2232compatibility with the standard @code{Assertion_Policy} pragma. The check 2233policy setting @code{DISABLE} causes the second argument of a corresponding 2234@code{Check} pragma to be completely ignored and not analyzed. 2235 2236@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2237@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{36} 2238@section Pragma Comment 2239 2240 2241Syntax: 2242 2243@example 2244pragma Comment (static_string_EXPRESSION); 2245@end example 2246 2247This is almost identical in effect to pragma @code{Ident}. It allows the 2248placement of a comment into the object file and hence into the 2249executable file if the operating system permits such usage. The 2250difference is that @code{Comment}, unlike @code{Ident}, has 2251no limitations on placement of the pragma (it can be placed 2252anywhere in the main source unit), and if more than one pragma 2253is used, all comments are retained. 2254 2255@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2256@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{37} 2257@section Pragma Common_Object 2258 2259 2260Syntax: 2261 2262@example 2263pragma Common_Object ( 2264 [Internal =>] LOCAL_NAME 2265 [, [External =>] EXTERNAL_SYMBOL] 2266 [, [Size =>] EXTERNAL_SYMBOL] ); 2267 2268EXTERNAL_SYMBOL ::= 2269 IDENTIFIER 2270| static_string_EXPRESSION 2271@end example 2272 2273This pragma enables the shared use of variables stored in overlaid 2274linker areas corresponding to the use of @code{COMMON} 2275in Fortran. The single 2276object @code{LOCAL_NAME} is assigned to the area designated by 2277the @code{External} argument. 2278You may define a record to correspond to a series 2279of fields. The @code{Size} argument 2280is syntax checked in GNAT, but otherwise ignored. 2281 2282@code{Common_Object} is not supported on all platforms. If no 2283support is available, then the code generator will issue a message 2284indicating that the necessary attribute for implementation of this 2285pragma is not available. 2286 2287@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2288@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{38} 2289@section Pragma Compile_Time_Error 2290 2291 2292Syntax: 2293 2294@example 2295pragma Compile_Time_Error 2296 (boolean_EXPRESSION, static_string_EXPRESSION); 2297@end example 2298 2299This pragma can be used to generate additional compile time 2300error messages. It 2301is particularly useful in generics, where errors can be issued for 2302specific problematic instantiations. The first parameter is a boolean 2303expression. The pragma is effective only if the value of this expression 2304is known at compile time, and has the value True. The set of expressions 2305whose values are known at compile time includes all static boolean 2306expressions, and also other values which the compiler can determine 2307at compile time (e.g., the size of a record type set by an explicit 2308size representation clause, or the value of a variable which was 2309initialized to a constant and is known not to have been modified). 2310If these conditions are met, an error message is generated using 2311the value given as the second argument. This string value may contain 2312embedded ASCII.LF characters to break the message into multiple lines. 2313 2314@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2315@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{39} 2316@section Pragma Compile_Time_Warning 2317 2318 2319Syntax: 2320 2321@example 2322pragma Compile_Time_Warning 2323 (boolean_EXPRESSION, static_string_EXPRESSION); 2324@end example 2325 2326Same as pragma Compile_Time_Error, except a warning is issued instead 2327of an error message. Note that if this pragma is used in a package that 2328is with'ed by a client, the client will get the warning even though it 2329is issued by a with'ed package (normally warnings in with'ed units are 2330suppressed, but this is a special exception to that rule). 2331 2332One typical use is within a generic where compile time known characteristics 2333of formal parameters are tested, and warnings given appropriately. Another use 2334with a first parameter of True is to warn a client about use of a package, 2335for example that it is not fully implemented. 2336 2337@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2338@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3a} 2339@section Pragma Compiler_Unit 2340 2341 2342Syntax: 2343 2344@example 2345pragma Compiler_Unit; 2346@end example 2347 2348This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2349retained so that old versions of the GNAT run-time that use this pragma can 2350be compiled with newer versions of the compiler. 2351 2352@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2353@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3b} 2354@section Pragma Compiler_Unit_Warning 2355 2356 2357Syntax: 2358 2359@example 2360pragma Compiler_Unit_Warning; 2361@end example 2362 2363This pragma is intended only for internal use in the GNAT run-time library. 2364It indicates that the unit is used as part of the compiler build. The effect 2365is to generate warnings for the use of constructs (for example, conditional 2366expressions) that would cause trouble when bootstrapping using an older 2367version of GNAT. For the exact list of restrictions, see the compiler sources 2368and references to Check_Compiler_Unit. 2369 2370@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2371@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3c} 2372@section Pragma Complete_Representation 2373 2374 2375Syntax: 2376 2377@example 2378pragma Complete_Representation; 2379@end example 2380 2381This pragma must appear immediately within a record representation 2382clause. Typical placements are before the first component clause 2383or after the last component clause. The effect is to give an error 2384message if any component is missing a component clause. This pragma 2385may be used to ensure that a record representation clause is 2386complete, and that this invariant is maintained if fields are 2387added to the record in the future. 2388 2389@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2390@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3d} 2391@section Pragma Complex_Representation 2392 2393 2394Syntax: 2395 2396@example 2397pragma Complex_Representation 2398 ([Entity =>] LOCAL_NAME); 2399@end example 2400 2401The @code{Entity} argument must be the name of a record type which has 2402two fields of the same floating-point type. The effect of this pragma is 2403to force gcc to use the special internal complex representation form for 2404this record, which may be more efficient. Note that this may result in 2405the code for this type not conforming to standard ABI (application 2406binary interface) requirements for the handling of record types. For 2407example, in some environments, there is a requirement for passing 2408records by pointer, and the use of this pragma may result in passing 2409this type in floating-point registers. 2410 2411@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2412@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{3e} 2413@section Pragma Component_Alignment 2414 2415 2416@geindex Alignments of components 2417 2418@geindex Pragma Component_Alignment 2419 2420Syntax: 2421 2422@example 2423pragma Component_Alignment ( 2424 [Form =>] ALIGNMENT_CHOICE 2425 [, [Name =>] type_LOCAL_NAME]); 2426 2427ALIGNMENT_CHOICE ::= 2428 Component_Size 2429| Component_Size_4 2430| Storage_Unit 2431| Default 2432@end example 2433 2434Specifies the alignment of components in array or record types. 2435The meaning of the @code{Form} argument is as follows: 2436 2437@quotation 2438 2439@geindex Component_Size (in pragma Component_Alignment) 2440@end quotation 2441 2442 2443@table @asis 2444 2445@item @emph{Component_Size} 2446 2447Aligns scalar components and subcomponents of the array or record type 2448on boundaries appropriate to their inherent size (naturally 2449aligned). For example, 1-byte components are aligned on byte boundaries, 24502-byte integer components are aligned on 2-byte boundaries, 4-byte 2451integer components are aligned on 4-byte boundaries and so on. These 2452alignment rules correspond to the normal rules for C compilers on all 2453machines except the VAX. 2454 2455@geindex Component_Size_4 (in pragma Component_Alignment) 2456 2457@item @emph{Component_Size_4} 2458 2459Naturally aligns components with a size of four or fewer 2460bytes. Components that are larger than 4 bytes are placed on the next 24614-byte boundary. 2462 2463@geindex Storage_Unit (in pragma Component_Alignment) 2464 2465@item @emph{Storage_Unit} 2466 2467Specifies that array or record components are byte aligned, i.e., 2468aligned on boundaries determined by the value of the constant 2469@code{System.Storage_Unit}. 2470 2471@geindex Default (in pragma Component_Alignment) 2472 2473@item @emph{Default} 2474 2475Specifies that array or record components are aligned on default 2476boundaries, appropriate to the underlying hardware or operating system or 2477both. The @code{Default} choice is the same as @code{Component_Size} (natural 2478alignment). 2479@end table 2480 2481If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must 2482refer to a local record or array type, and the specified alignment 2483choice applies to the specified type. The use of 2484@code{Component_Alignment} together with a pragma @code{Pack} causes the 2485@code{Component_Alignment} pragma to be ignored. The use of 2486@code{Component_Alignment} together with a record representation clause 2487is only effective for fields not specified by the representation clause. 2488 2489If the @code{Name} parameter is absent, the pragma can be used as either 2490a configuration pragma, in which case it applies to one or more units in 2491accordance with the normal rules for configuration pragmas, or it can be 2492used within a declarative part, in which case it applies to types that 2493are declared within this declarative part, or within any nested scope 2494within this declarative part. In either case it specifies the alignment 2495to be applied to any record or array type which has otherwise standard 2496representation. 2497 2498If the alignment for a record or array type is not specified (using 2499pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2500clause), the GNAT uses the default alignment as described previously. 2501 2502@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2503@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{3f}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{40} 2504@section Pragma Constant_After_Elaboration 2505 2506 2507Syntax: 2508 2509@example 2510pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2511@end example 2512 2513For the semantics of this pragma, see the entry for aspect 2514@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2515 2516@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2517@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{42} 2518@section Pragma Contract_Cases 2519 2520 2521@geindex Contract cases 2522 2523Syntax: 2524 2525@example 2526pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2527 2528CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2529 2530CASE_GUARD ::= boolean_EXPRESSION | others 2531 2532CONSEQUENCE ::= boolean_EXPRESSION 2533@end example 2534 2535The @code{Contract_Cases} pragma allows defining fine-grain specifications 2536that can complement or replace the contract given by a precondition and a 2537postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2538by testing and formal verification tools. The compiler checks its validity and, 2539depending on the assertion policy at the point of declaration of the pragma, 2540it may insert a check in the executable. For code generation, the contract 2541cases 2542 2543@example 2544pragma Contract_Cases ( 2545 Cond1 => Pred1, 2546 Cond2 => Pred2); 2547@end example 2548 2549are equivalent to 2550 2551@example 2552C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2553C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2554pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2555pragma Postcondition (if C1 then Pred1); 2556pragma Postcondition (if C2 then Pred2); 2557@end example 2558 2559The precondition ensures that one and only one of the conditions is 2560satisfied on entry to the subprogram. 2561The postcondition ensures that for the condition that was True on entry, 2562the corrresponding consequence is True on exit. Other consequence expressions 2563are not evaluated. 2564 2565A precondition @code{P} and postcondition @code{Q} can also be 2566expressed as contract cases: 2567 2568@example 2569pragma Contract_Cases (P => Q); 2570@end example 2571 2572The placement and visibility rules for @code{Contract_Cases} pragmas are 2573identical to those described for preconditions and postconditions. 2574 2575The compiler checks that boolean expressions given in conditions and 2576consequences are valid, where the rules for conditions are the same as 2577the rule for an expression in @code{Precondition} and the rules for 2578consequences are the same as the rule for an expression in 2579@code{Postcondition}. In particular, attributes @code{'Old} and 2580@code{'Result} can only be used within consequence expressions. 2581The condition for the last contract case may be @code{others}, to denote 2582any case not captured by the previous cases. The 2583following is an example of use within a package spec: 2584 2585@example 2586package Math_Functions is 2587 ... 2588 function Sqrt (Arg : Float) return Float; 2589 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 2590 Arg >= 100.0 => Sqrt'Result >= 10.0, 2591 others => Sqrt'Result = 0.0)); 2592 ... 2593end Math_Functions; 2594@end example 2595 2596The meaning of contract cases is that only one case should apply at each 2597call, as determined by the corresponding condition evaluating to True, 2598and that the consequence for this case should hold when the subprogram 2599returns. 2600 2601@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2602@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{43} 2603@section Pragma Convention_Identifier 2604 2605 2606@geindex Conventions 2607@geindex synonyms 2608 2609Syntax: 2610 2611@example 2612pragma Convention_Identifier ( 2613 [Name =>] IDENTIFIER, 2614 [Convention =>] convention_IDENTIFIER); 2615@end example 2616 2617This pragma provides a mechanism for supplying synonyms for existing 2618convention identifiers. The @code{Name} identifier can subsequently 2619be used as a synonym for the given convention in other pragmas (including 2620for example pragma @code{Import} or another @code{Convention_Identifier} 2621pragma). As an example of the use of this, suppose you had legacy code 2622which used Fortran77 as the identifier for Fortran. Then the pragma: 2623 2624@example 2625pragma Convention_Identifier (Fortran77, Fortran); 2626@end example 2627 2628would allow the use of the convention identifier @code{Fortran77} in 2629subsequent code, avoiding the need to modify the sources. As another 2630example, you could use this to parameterize convention requirements 2631according to systems. Suppose you needed to use @code{Stdcall} on 2632windows systems, and @code{C} on some other system, then you could 2633define a convention identifier @code{Library} and use a single 2634@code{Convention_Identifier} pragma to specify which convention 2635would be used system-wide. 2636 2637@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2638@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{44} 2639@section Pragma CPP_Class 2640 2641 2642@geindex Interfacing with C++ 2643 2644Syntax: 2645 2646@example 2647pragma CPP_Class ([Entity =>] LOCAL_NAME); 2648@end example 2649 2650The argument denotes an entity in the current declarative region that is 2651declared as a record type. It indicates that the type corresponds to an 2652externally declared C++ class type, and is to be laid out the same way 2653that C++ would lay out the type. If the C++ class has virtual primitives 2654then the record must be declared as a tagged record type. 2655 2656Types for which @code{CPP_Class} is specified do not have assignment or 2657equality operators defined (such operations can be imported or declared 2658as subprograms as required). Initialization is allowed only by constructor 2659functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2660limited if not explicitly declared as limited or derived from a limited 2661type, and an error is issued in that case. 2662 2663See @ref{45,,Interfacing to C++} for related information. 2664 2665Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2666for backward compatibility but its functionality is available 2667using pragma @code{Import} with @code{Convention} = @code{CPP}. 2668 2669@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2670@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{46} 2671@section Pragma CPP_Constructor 2672 2673 2674@geindex Interfacing with C++ 2675 2676Syntax: 2677 2678@example 2679pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2680 [, [External_Name =>] static_string_EXPRESSION ] 2681 [, [Link_Name =>] static_string_EXPRESSION ]); 2682@end example 2683 2684This pragma identifies an imported function (imported in the usual way 2685with pragma @code{Import}) as corresponding to a C++ constructor. If 2686@code{External_Name} and @code{Link_Name} are not specified then the 2687@code{Entity} argument is a name that must have been previously mentioned 2688in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2689must be of one of the following forms: 2690 2691 2692@itemize * 2693 2694@item 2695@strong{function} @code{Fname} @strong{return} T` 2696 2697@item 2698@strong{function} @code{Fname} @strong{return} T'Class 2699 2700@item 2701@strong{function} @code{Fname} (...) @strong{return} T` 2702 2703@item 2704@strong{function} @code{Fname} (...) @strong{return} T'Class 2705@end itemize 2706 2707where @code{T} is a limited record type imported from C++ with pragma 2708@code{Import} and @code{Convention} = @code{CPP}. 2709 2710The first two forms import the default constructor, used when an object 2711of type @code{T} is created on the Ada side with no explicit constructor. 2712The latter two forms cover all the non-default constructors of the type. 2713See the GNAT User's Guide for details. 2714 2715If no constructors are imported, it is impossible to create any objects 2716on the Ada side and the type is implicitly declared abstract. 2717 2718Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2719using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2720GCC switch). 2721See @ref{45,,Interfacing to C++} for more related information. 2722 2723Note: The use of functions returning class-wide types for constructors is 2724currently obsolete. They are supported for backward compatibility. The 2725use of functions returning the type T leave the Ada sources more clear 2726because the imported C++ constructors always return an object of type T; 2727that is, they never return an object whose type is a descendant of type T. 2728 2729@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2730@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{47} 2731@section Pragma CPP_Virtual 2732 2733 2734@geindex Interfacing to C++ 2735 2736This pragma is now obsolete and, other than generating a warning if warnings 2737on obsolescent features are enabled, is completely ignored. 2738It is retained for compatibility 2739purposes. It used to be required to ensure compoatibility with C++, but 2740is no longer required for that purpose because GNAT generates 2741the same object layout as the G++ compiler by default. 2742 2743See @ref{45,,Interfacing to C++} for related information. 2744 2745@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2746@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{48} 2747@section Pragma CPP_Vtable 2748 2749 2750@geindex Interfacing with C++ 2751 2752This pragma is now obsolete and, other than generating a warning if warnings 2753on obsolescent features are enabled, is completely ignored. 2754It used to be required to ensure compatibility with C++, but 2755is no longer required for that purpose because GNAT generates 2756the same object layout as the G++ compiler by default. 2757 2758See @ref{45,,Interfacing to C++} for related information. 2759 2760@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas 2761@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{49} 2762@section Pragma CPU 2763 2764 2765Syntax: 2766 2767@example 2768pragma CPU (EXPRESSION); 2769@end example 2770 2771This pragma is standard in Ada 2012, but is available in all earlier 2772versions of Ada as an implementation-defined pragma. 2773See Ada 2012 Reference Manual for details. 2774 2775@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas 2776@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4a} 2777@section Pragma Deadline_Floor 2778 2779 2780Syntax: 2781 2782@example 2783pragma Deadline_Floor (time_span_EXPRESSION); 2784@end example 2785 2786This pragma applies only to protected types and specifies the floor 2787deadline inherited by a task when the task enters a protected object. 2788It is effective only when the EDF scheduling policy is used. 2789 2790@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas 2791@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4b}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4c} 2792@section Pragma Default_Initial_Condition 2793 2794 2795Syntax: 2796 2797@example 2798pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2799@end example 2800 2801For the semantics of this pragma, see the entry for aspect 2802@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2803 2804@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2805@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4d} 2806@section Pragma Debug 2807 2808 2809Syntax: 2810 2811@example 2812pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2813 2814PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2815 PROCEDURE_NAME 2816| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2817@end example 2818 2819The procedure call argument has the syntactic form of an expression, meeting 2820the syntactic requirements for pragmas. 2821 2822If debug pragmas are not enabled or if the condition is present and evaluates 2823to False, this pragma has no effect. If debug pragmas are enabled, the 2824semantics of the pragma is exactly equivalent to the procedure call statement 2825corresponding to the argument with a terminating semicolon. Pragmas are 2826permitted in sequences of declarations, so you can use pragma @code{Debug} to 2827intersperse calls to debug procedures in the middle of declarations. Debug 2828pragmas can be enabled either by use of the command line switch @emph{-gnata} 2829or by use of the pragma @code{Check_Policy} with a first argument of 2830@code{Debug}. 2831 2832@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 2833@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{4e} 2834@section Pragma Debug_Policy 2835 2836 2837Syntax: 2838 2839@example 2840pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 2841@end example 2842 2843This pragma is equivalent to a corresponding @code{Check_Policy} pragma 2844with a first argument of @code{Debug}. It is retained for historical 2845compatibility reasons. 2846 2847@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 2848@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{4f} 2849@section Pragma Default_Scalar_Storage_Order 2850 2851 2852@geindex Default_Scalar_Storage_Order 2853 2854@geindex Scalar_Storage_Order 2855 2856Syntax: 2857 2858@example 2859pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 2860@end example 2861 2862Normally if no explicit @code{Scalar_Storage_Order} is given for a record 2863type or array type, then the scalar storage order defaults to the ordinary 2864default for the target. But this default may be overridden using this pragma. 2865The pragma may appear as a configuration pragma, or locally within a package 2866spec or declarative part. In the latter case, it applies to all subsequent 2867types declared within that package spec or declarative part. 2868 2869The following example shows the use of this pragma: 2870 2871@example 2872pragma Default_Scalar_Storage_Order (High_Order_First); 2873with System; use System; 2874package DSSO1 is 2875 type H1 is record 2876 a : Integer; 2877 end record; 2878 2879 type L2 is record 2880 a : Integer; 2881 end record; 2882 for L2'Scalar_Storage_Order use Low_Order_First; 2883 2884 type L2a is new L2; 2885 2886 package Inner is 2887 type H3 is record 2888 a : Integer; 2889 end record; 2890 2891 pragma Default_Scalar_Storage_Order (Low_Order_First); 2892 2893 type L4 is record 2894 a : Integer; 2895 end record; 2896 end Inner; 2897 2898 type H4a is new Inner.L4; 2899 2900 type H5 is record 2901 a : Integer; 2902 end record; 2903end DSSO1; 2904@end example 2905 2906In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar 2907storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. 2908Note that in the case of @code{H4a}, the order is not inherited 2909from the parent type. Only an explicitly set @code{Scalar_Storage_Order} 2910gets inherited on type derivation. 2911 2912If this pragma is used as a configuration pragma which appears within a 2913configuration pragma file (as opposed to appearing explicitly at the start 2914of a single unit), then the binder will require that all units in a partition 2915be compiled in a similar manner, other than run-time units, which are not 2916affected by this pragma. Note that the use of this form is discouraged because 2917it may significantly degrade the run-time performance of the software, instead 2918the default scalar storage order ought to be changed only on a local basis. 2919 2920@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 2921@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{50} 2922@section Pragma Default_Storage_Pool 2923 2924 2925@geindex Default_Storage_Pool 2926 2927Syntax: 2928 2929@example 2930pragma Default_Storage_Pool (storage_pool_NAME | null); 2931@end example 2932 2933This pragma is standard in Ada 2012, but is available in all earlier 2934versions of Ada as an implementation-defined pragma. 2935See Ada 2012 Reference Manual for details. 2936 2937@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 2938@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{51}@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{52} 2939@section Pragma Depends 2940 2941 2942Syntax: 2943 2944@example 2945pragma Depends (DEPENDENCY_RELATION); 2946 2947DEPENDENCY_RELATION ::= 2948 null 2949 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 2950 2951DEPENDENCY_CLAUSE ::= 2952 OUTPUT_LIST =>[+] INPUT_LIST 2953 | NULL_DEPENDENCY_CLAUSE 2954 2955NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 2956 2957OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 2958 2959INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 2960 2961OUTPUT ::= NAME | FUNCTION_RESULT 2962INPUT ::= NAME 2963 2964where FUNCTION_RESULT is a function Result attribute_reference 2965@end example 2966 2967For the semantics of this pragma, see the entry for aspect @code{Depends} in the 2968SPARK 2014 Reference Manual, section 6.1.5. 2969 2970@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 2971@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{53} 2972@section Pragma Detect_Blocking 2973 2974 2975Syntax: 2976 2977@example 2978pragma Detect_Blocking; 2979@end example 2980 2981This is a standard pragma in Ada 2005, that is available in all earlier 2982versions of Ada as an implementation-defined pragma. 2983 2984This is a configuration pragma that forces the detection of potentially 2985blocking operations within a protected operation, and to raise Program_Error 2986if that happens. 2987 2988@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 2989@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{54} 2990@section Pragma Disable_Atomic_Synchronization 2991 2992 2993@geindex Atomic Synchronization 2994 2995Syntax: 2996 2997@example 2998pragma Disable_Atomic_Synchronization [(Entity)]; 2999@end example 3000 3001Ada requires that accesses (reads or writes) of an atomic variable be 3002regarded as synchronization points in the case of multiple tasks. 3003Particularly in the case of multi-processors this may require special 3004handling, e.g. the generation of memory barriers. This capability may 3005be turned off using this pragma in cases where it is known not to be 3006required. 3007 3008The placement and scope rules for this pragma are the same as those 3009for @code{pragma Suppress}. In particular it can be used as a 3010configuration pragma, or in a declaration sequence where it applies 3011till the end of the scope. If an @code{Entity} argument is present, 3012the action applies only to that entity. 3013 3014@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 3015@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{55} 3016@section Pragma Dispatching_Domain 3017 3018 3019Syntax: 3020 3021@example 3022pragma Dispatching_Domain (EXPRESSION); 3023@end example 3024 3025This pragma is standard in Ada 2012, but is available in all earlier 3026versions of Ada as an implementation-defined pragma. 3027See Ada 2012 Reference Manual for details. 3028 3029@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 3030@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{56}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{57} 3031@section Pragma Effective_Reads 3032 3033 3034Syntax: 3035 3036@example 3037pragma Effective_Reads [ (boolean_EXPRESSION) ]; 3038@end example 3039 3040For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in 3041the SPARK 2014 Reference Manual, section 7.1.2. 3042 3043@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3044@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{59} 3045@section Pragma Effective_Writes 3046 3047 3048Syntax: 3049 3050@example 3051pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3052@end example 3053 3054For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} 3055in the SPARK 2014 Reference Manual, section 7.1.2. 3056 3057@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3058@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5a} 3059@section Pragma Elaboration_Checks 3060 3061 3062@geindex Elaboration control 3063 3064Syntax: 3065 3066@example 3067pragma Elaboration_Checks (Dynamic | Static); 3068@end example 3069 3070This is a configuration pragma that provides control over the 3071elaboration model used by the compilation affected by the 3072pragma. If the parameter is @code{Dynamic}, 3073then the dynamic elaboration 3074model described in the Ada Reference Manual is used, as though 3075the @emph{-gnatE} switch had been specified on the command 3076line. If the parameter is @code{Static}, then the default GNAT static 3077model is used. This configuration pragma overrides the setting 3078of the command line. For full details on the elaboration models 3079used by the GNAT compiler, see the chapter on elaboration order handling 3080in the @emph{GNAT User's Guide}. 3081 3082@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3083@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5b} 3084@section Pragma Eliminate 3085 3086 3087@geindex Elimination of unused subprograms 3088 3089Syntax: 3090 3091@example 3092pragma Eliminate ( 3093 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 3094 [ Entity => ] IDENTIFIER | 3095 SELECTED_COMPONENT | 3096 STRING_LITERAL 3097 [, Source_Location => SOURCE_TRACE ] ); 3098 3099 SOURCE_TRACE ::= STRING_LITERAL 3100@end example 3101 3102This pragma indicates that the given entity is not used in the program to be 3103compiled and built, thus allowing the compiler to 3104eliminate the code or data associated with the named entity. Any reference to 3105an eliminated entity causes a compile-time or link-time error. 3106 3107The pragma has the following semantics, where @code{U} is the unit specified by 3108the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} 3109argument: 3110 3111 3112@itemize * 3113 3114@item 3115@code{E} must be a subprogram that is explicitly declared either: 3116 3117o Within @code{U}, or 3118 3119o Within a generic package that is instantiated in @code{U}, or 3120 3121o As an instance of generic subprogram instantiated in @code{U}. 3122 3123Otherwise the pragma is ignored. 3124 3125@item 3126If @code{E} is overloaded within @code{U} then, in the absence of a 3127@code{Source_Location} argument, all overloadings are eliminated. 3128 3129@item 3130If @code{E} is overloaded within @code{U} and only some overloadings 3131are to be eliminated, then each overloading to be eliminated 3132must be specified in a corresponding pragma @code{Eliminate} 3133with a @code{Source_Location} argument identifying the line where the 3134declaration appears, as described below. 3135 3136@item 3137If @code{E} is declared as the result of a generic instantiation, then 3138a @code{Source_Location} argument is needed, as described below 3139@end itemize 3140 3141Pragma @code{Eliminate} allows a program to be compiled in a system-independent 3142manner, so that unused entities are eliminated but without 3143needing to modify the source text. Normally the required set of 3144@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. 3145 3146Any source file change that removes, splits, or 3147adds lines may make the set of @code{Eliminate} pragmas invalid because their 3148@code{Source_Location} argument values may get out of date. 3149 3150Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 3151operation. In this case all the subprograms to which the given operation can 3152dispatch are considered to be unused (are never called as a result of a direct 3153or a dispatching call). 3154 3155The string literal given for the source location specifies the line number 3156of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: 3157 3158@example 3159SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 3160 3161LBRACKET ::= '[' 3162RBRACKET ::= ']' 3163 3164SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3165 3166LINE_NUMBER ::= DIGIT @{DIGIT@} 3167@end example 3168 3169Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. 3170 3171The source trace that is given as the @code{Source_Location} must obey the 3172following rules (or else the pragma is ignored), where @code{U} is 3173the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the 3174subprogram specified by the @code{Entity} argument: 3175 3176 3177@itemize * 3178 3179@item 3180@code{FILE_NAME} is the short name (with no directory 3181information) of the Ada source file for @code{U}, using the required syntax 3182for the underlying file system (e.g. case is significant if the underlying 3183operating system is case sensitive). 3184If @code{U} is a package and @code{E} is a subprogram declared in the package 3185specification and its full declaration appears in the package body, 3186then the relevant source file is the one for the package specification; 3187analogously if @code{U} is a generic package. 3188 3189@item 3190If @code{E} is not declared in a generic instantiation (this includes 3191generic subprogram instances), the source trace includes only one source 3192line reference. @code{LINE_NUMBER} gives the line number of the occurrence 3193of the declaration of @code{E} within the source file (as a decimal literal 3194without an exponent or point). 3195 3196@item 3197If @code{E} is declared by a generic instantiation, its source trace 3198(from left to right) starts with the source location of the 3199declaration of @code{E} in the generic unit and ends with the source 3200location of the instantiation, given in square brackets. This approach is 3201applied recursively with nested instantiations: the rightmost (nested 3202most deeply in square brackets) element of the source trace is the location 3203of the outermost instantiation, and the leftmost element (that is, outside 3204of any square brackets) is the location of the declaration of @code{E} in 3205the generic unit. 3206@end itemize 3207 3208Examples: 3209 3210@quotation 3211 3212@example 3213pragma Eliminate (Pkg0, Proc); 3214-- Eliminate (all overloadings of) Proc in Pkg0 3215 3216pragma Eliminate (Pkg1, Proc, 3217 Source_Location => "pkg1.ads:8"); 3218-- Eliminate overloading of Proc at line 8 in pkg1.ads 3219 3220-- Assume the following file contents: 3221-- gen_pkg.ads 3222-- 1: generic 3223-- 2: type T is private; 3224-- 3: package Gen_Pkg is 3225-- 4: procedure Proc(N : T); 3226-- ... ... 3227-- ... end Gen_Pkg; 3228-- 3229-- q.adb 3230-- 1: with Gen_Pkg; 3231-- 2: procedure Q is 3232-- 3: package Inst_Pkg is new Gen_Pkg(Integer); 3233-- ... -- No calls on Inst_Pkg.Proc 3234-- ... end Q; 3235 3236-- The following pragma eliminates Inst_Pkg.Proc from Q 3237pragma Eliminate (Q, Proc, 3238 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 3239@end example 3240@end quotation 3241 3242@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3243@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5c} 3244@section Pragma Enable_Atomic_Synchronization 3245 3246 3247@geindex Atomic Synchronization 3248 3249Syntax: 3250 3251@example 3252pragma Enable_Atomic_Synchronization [(Entity)]; 3253@end example 3254 3255Ada requires that accesses (reads or writes) of an atomic variable be 3256regarded as synchronization points in the case of multiple tasks. 3257Particularly in the case of multi-processors this may require special 3258handling, e.g. the generation of memory barriers. This synchronization 3259is performed by default, but can be turned off using 3260@code{pragma Disable_Atomic_Synchronization}. The 3261@code{Enable_Atomic_Synchronization} pragma can be used to turn 3262it back on. 3263 3264The placement and scope rules for this pragma are the same as those 3265for @code{pragma Unsuppress}. In particular it can be used as a 3266configuration pragma, or in a declaration sequence where it applies 3267till the end of the scope. If an @code{Entity} argument is present, 3268the action applies only to that entity. 3269 3270@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3271@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5d} 3272@section Pragma Export_Function 3273 3274 3275@geindex Argument passing mechanisms 3276 3277Syntax: 3278 3279@example 3280pragma Export_Function ( 3281 [Internal =>] LOCAL_NAME 3282 [, [External =>] EXTERNAL_SYMBOL] 3283 [, [Parameter_Types =>] PARAMETER_TYPES] 3284 [, [Result_Type =>] result_SUBTYPE_MARK] 3285 [, [Mechanism =>] MECHANISM] 3286 [, [Result_Mechanism =>] MECHANISM_NAME]); 3287 3288EXTERNAL_SYMBOL ::= 3289 IDENTIFIER 3290| static_string_EXPRESSION 3291| "" 3292 3293PARAMETER_TYPES ::= 3294 null 3295| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3296 3297TYPE_DESIGNATOR ::= 3298 subtype_NAME 3299| subtype_Name ' Access 3300 3301MECHANISM ::= 3302 MECHANISM_NAME 3303| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3304 3305MECHANISM_ASSOCIATION ::= 3306 [formal_parameter_NAME =>] MECHANISM_NAME 3307 3308MECHANISM_NAME ::= Value | Reference 3309@end example 3310 3311Use this pragma to make a function externally callable and optionally 3312provide information on mechanisms to be used for passing parameter and 3313result values. We recommend, for the purposes of improving portability, 3314this pragma always be used in conjunction with a separate pragma 3315@code{Export}, which must precede the pragma @code{Export_Function}. 3316GNAT does not require a separate pragma @code{Export}, but if none is 3317present, @code{Convention Ada} is assumed, which is usually 3318not what is wanted, so it is usually appropriate to use this 3319pragma in conjunction with a @code{Export} or @code{Convention} 3320pragma that specifies the desired foreign convention. 3321Pragma @code{Export_Function} 3322(and @code{Export}, if present) must appear in the same declarative 3323region as the function to which they apply. 3324 3325The @code{internal_name} must uniquely designate the function to which the 3326pragma applies. If more than one function name exists of this name in 3327the declarative part you must use the @code{Parameter_Types} and 3328@code{Result_Type} parameters to achieve the required 3329unique designation. The @cite{subtype_mark}s in these parameters must 3330exactly match the subtypes in the corresponding function specification, 3331using positional notation to match parameters with subtype marks. 3332The form with an @code{'Access} attribute can be used to match an 3333anonymous access parameter. 3334 3335@geindex Suppressing external name 3336 3337Special treatment is given if the EXTERNAL is an explicit null 3338string or a static string expressions that evaluates to the null 3339string. In this case, no external name is generated. This form 3340still allows the specification of parameter mechanisms. 3341 3342@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3343@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{5e} 3344@section Pragma Export_Object 3345 3346 3347Syntax: 3348 3349@example 3350pragma Export_Object 3351 [Internal =>] LOCAL_NAME 3352 [, [External =>] EXTERNAL_SYMBOL] 3353 [, [Size =>] EXTERNAL_SYMBOL] 3354 3355EXTERNAL_SYMBOL ::= 3356 IDENTIFIER 3357| static_string_EXPRESSION 3358@end example 3359 3360This pragma designates an object as exported, and apart from the 3361extended rules for external symbols, is identical in effect to the use of 3362the normal @code{Export} pragma applied to an object. You may use a 3363separate Export pragma (and you probably should from the point of view 3364of portability), but it is not required. @code{Size} is syntax checked, 3365but otherwise ignored by GNAT. 3366 3367@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas 3368@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{5f} 3369@section Pragma Export_Procedure 3370 3371 3372Syntax: 3373 3374@example 3375pragma Export_Procedure ( 3376 [Internal =>] LOCAL_NAME 3377 [, [External =>] EXTERNAL_SYMBOL] 3378 [, [Parameter_Types =>] PARAMETER_TYPES] 3379 [, [Mechanism =>] MECHANISM]); 3380 3381EXTERNAL_SYMBOL ::= 3382 IDENTIFIER 3383| static_string_EXPRESSION 3384| "" 3385 3386PARAMETER_TYPES ::= 3387 null 3388| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3389 3390TYPE_DESIGNATOR ::= 3391 subtype_NAME 3392| subtype_Name ' Access 3393 3394MECHANISM ::= 3395 MECHANISM_NAME 3396| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3397 3398MECHANISM_ASSOCIATION ::= 3399 [formal_parameter_NAME =>] MECHANISM_NAME 3400 3401MECHANISM_NAME ::= Value | Reference 3402@end example 3403 3404This pragma is identical to @code{Export_Function} except that it 3405applies to a procedure rather than a function and the parameters 3406@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3407GNAT does not require a separate pragma @code{Export}, but if none is 3408present, @code{Convention Ada} is assumed, which is usually 3409not what is wanted, so it is usually appropriate to use this 3410pragma in conjunction with a @code{Export} or @code{Convention} 3411pragma that specifies the desired foreign convention. 3412 3413@geindex Suppressing external name 3414 3415Special treatment is given if the EXTERNAL is an explicit null 3416string or a static string expressions that evaluates to the null 3417string. In this case, no external name is generated. This form 3418still allows the specification of parameter mechanisms. 3419 3420@node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas 3421@anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{60} 3422@section Pragma Export_Value 3423 3424 3425Syntax: 3426 3427@example 3428pragma Export_Value ( 3429 [Value =>] static_integer_EXPRESSION, 3430 [Link_Name =>] static_string_EXPRESSION); 3431@end example 3432 3433This pragma serves to export a static integer value for external use. 3434The first argument specifies the value to be exported. The Link_Name 3435argument specifies the symbolic name to be associated with the integer 3436value. This pragma is useful for defining a named static value in Ada 3437that can be referenced in assembly language units to be linked with 3438the application. This pragma is currently supported only for the 3439AAMP target and is ignored for other targets. 3440 3441@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas 3442@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{61} 3443@section Pragma Export_Valued_Procedure 3444 3445 3446Syntax: 3447 3448@example 3449pragma Export_Valued_Procedure ( 3450 [Internal =>] LOCAL_NAME 3451 [, [External =>] EXTERNAL_SYMBOL] 3452 [, [Parameter_Types =>] PARAMETER_TYPES] 3453 [, [Mechanism =>] MECHANISM]); 3454 3455EXTERNAL_SYMBOL ::= 3456 IDENTIFIER 3457| static_string_EXPRESSION 3458| "" 3459 3460PARAMETER_TYPES ::= 3461 null 3462| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3463 3464TYPE_DESIGNATOR ::= 3465 subtype_NAME 3466| subtype_Name ' Access 3467 3468MECHANISM ::= 3469 MECHANISM_NAME 3470| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3471 3472MECHANISM_ASSOCIATION ::= 3473 [formal_parameter_NAME =>] MECHANISM_NAME 3474 3475MECHANISM_NAME ::= Value | Reference 3476@end example 3477 3478This pragma is identical to @code{Export_Procedure} except that the 3479first parameter of @code{LOCAL_NAME}, which must be present, must be of 3480mode @code{out}, and externally the subprogram is treated as a function 3481with this parameter as the result of the function. GNAT provides for 3482this capability to allow the use of @code{out} and @code{in out} 3483parameters in interfacing to external functions (which are not permitted 3484in Ada functions). 3485GNAT does not require a separate pragma @code{Export}, but if none is 3486present, @code{Convention Ada} is assumed, which is almost certainly 3487not what is wanted since the whole point of this pragma is to interface 3488with foreign language functions, so it is usually appropriate to use this 3489pragma in conjunction with a @code{Export} or @code{Convention} 3490pragma that specifies the desired foreign convention. 3491 3492@geindex Suppressing external name 3493 3494Special treatment is given if the EXTERNAL is an explicit null 3495string or a static string expressions that evaluates to the null 3496string. In this case, no external name is generated. This form 3497still allows the specification of parameter mechanisms. 3498 3499@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3500@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{62} 3501@section Pragma Extend_System 3502 3503 3504@geindex System 3505@geindex extending 3506 3507@geindex DEC Ada 83 3508 3509Syntax: 3510 3511@example 3512pragma Extend_System ([Name =>] IDENTIFIER); 3513@end example 3514 3515This pragma is used to provide backwards compatibility with other 3516implementations that extend the facilities of package @code{System}. In 3517GNAT, @code{System} contains only the definitions that are present in 3518the Ada RM. However, other implementations, notably the DEC Ada 83 3519implementation, provide many extensions to package @code{System}. 3520 3521For each such implementation accommodated by this pragma, GNAT provides a 3522package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 3523implementation, which provides the required additional definitions. You 3524can use this package in two ways. You can @code{with} it in the normal 3525way and access entities either by selection or using a @code{use} 3526clause. In this case no special processing is required. 3527 3528However, if existing code contains references such as 3529@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended 3530definitions provided in package @code{System}, you may use this pragma 3531to extend visibility in @code{System} in a non-standard way that 3532provides greater compatibility with the existing code. Pragma 3533@code{Extend_System} is a configuration pragma whose single argument is 3534the name of the package containing the extended definition 3535(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3536control of this pragma will be processed using special visibility 3537processing that looks in package @code{System.Aux_@emph{xxx}} where 3538@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in 3539package @code{System}, but not found in package @code{System}. 3540 3541You can use this pragma either to access a predefined @code{System} 3542extension supplied with the compiler, for example @code{Aux_DEC} or 3543you can construct your own extension unit following the above 3544definition. Note that such a package is a child of @code{System} 3545and thus is considered part of the implementation. 3546To compile it you will have to use the @emph{-gnatg} switch 3547for compiling System units, as explained in the 3548GNAT User's Guide. 3549 3550@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3551@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{63} 3552@section Pragma Extensions_Allowed 3553 3554 3555@geindex Ada Extensions 3556 3557@geindex GNAT Extensions 3558 3559Syntax: 3560 3561@example 3562pragma Extensions_Allowed (On | Off); 3563@end example 3564 3565This configuration pragma enables or disables the implementation 3566extension mode (the use of Off as a parameter cancels the effect 3567of the @emph{-gnatX} command switch). 3568 3569In extension mode, the latest version of the Ada language is 3570implemented (currently Ada 2012), and in addition a small number 3571of GNAT specific extensions are recognized as follows: 3572 3573 3574@table @asis 3575 3576@item @emph{Constrained attribute for generic objects} 3577 3578The @code{Constrained} attribute is permitted for objects of 3579generic types. The result indicates if the corresponding actual 3580is constrained. 3581@end table 3582 3583@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3584@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{64}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{65} 3585@section Pragma Extensions_Visible 3586 3587 3588Syntax: 3589 3590@example 3591pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3592@end example 3593 3594For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} 3595in the SPARK 2014 Reference Manual, section 6.1.7. 3596 3597@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3598@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{66} 3599@section Pragma External 3600 3601 3602Syntax: 3603 3604@example 3605pragma External ( 3606 [ Convention =>] convention_IDENTIFIER, 3607 [ Entity =>] LOCAL_NAME 3608 [, [External_Name =>] static_string_EXPRESSION ] 3609 [, [Link_Name =>] static_string_EXPRESSION ]); 3610@end example 3611 3612This pragma is identical in syntax and semantics to pragma 3613@code{Export} as defined in the Ada Reference Manual. It is 3614provided for compatibility with some Ada 83 compilers that 3615used this pragma for exactly the same purposes as pragma 3616@code{Export} before the latter was standardized. 3617 3618@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3619@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{67} 3620@section Pragma External_Name_Casing 3621 3622 3623@geindex Dec Ada 83 casing compatibility 3624 3625@geindex External Names 3626@geindex casing 3627 3628@geindex Casing of External names 3629 3630Syntax: 3631 3632@example 3633pragma External_Name_Casing ( 3634 Uppercase | Lowercase 3635 [, Uppercase | Lowercase | As_Is]); 3636@end example 3637 3638This pragma provides control over the casing of external names associated 3639with Import and Export pragmas. There are two cases to consider: 3640 3641 3642@itemize * 3643 3644@item 3645Implicit external names 3646 3647Implicit external names are derived from identifiers. The most common case 3648arises when a standard Ada Import or Export pragma is used with only two 3649arguments, as in: 3650 3651@example 3652pragma Import (C, C_Routine); 3653@end example 3654 3655Since Ada is a case-insensitive language, the spelling of the identifier in 3656the Ada source program does not provide any information on the desired 3657casing of the external name, and so a convention is needed. In GNAT the 3658default treatment is that such names are converted to all lower case 3659letters. This corresponds to the normal C style in many environments. 3660The first argument of pragma @code{External_Name_Casing} can be used to 3661control this treatment. If @code{Uppercase} is specified, then the name 3662will be forced to all uppercase letters. If @code{Lowercase} is specified, 3663then the normal default of all lower case letters will be used. 3664 3665This same implicit treatment is also used in the case of extended DEC Ada 83 3666compatible Import and Export pragmas where an external name is explicitly 3667specified using an identifier rather than a string. 3668 3669@item 3670Explicit external names 3671 3672Explicit external names are given as string literals. The most common case 3673arises when a standard Ada Import or Export pragma is used with three 3674arguments, as in: 3675 3676@example 3677pragma Import (C, C_Routine, "C_routine"); 3678@end example 3679 3680In this case, the string literal normally provides the exact casing required 3681for the external name. The second argument of pragma 3682@code{External_Name_Casing} may be used to modify this behavior. 3683If @code{Uppercase} is specified, then the name 3684will be forced to all uppercase letters. If @code{Lowercase} is specified, 3685then the name will be forced to all lowercase letters. A specification of 3686@code{As_Is} provides the normal default behavior in which the casing is 3687taken from the string provided. 3688@end itemize 3689 3690This pragma may appear anywhere that a pragma is valid. In particular, it 3691can be used as a configuration pragma in the @code{gnat.adc} file, in which 3692case it applies to all subsequent compilations, or it can be used as a program 3693unit pragma, in which case it only applies to the current unit, or it can 3694be used more locally to control individual Import/Export pragmas. 3695 3696It was primarily intended for use with OpenVMS systems, where many 3697compilers convert all symbols to upper case by default. For interfacing to 3698such compilers (e.g., the DEC C compiler), it may be convenient to use 3699the pragma: 3700 3701@example 3702pragma External_Name_Casing (Uppercase, Uppercase); 3703@end example 3704 3705to enforce the upper casing of all external symbols. 3706 3707@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 3708@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{68} 3709@section Pragma Fast_Math 3710 3711 3712Syntax: 3713 3714@example 3715pragma Fast_Math; 3716@end example 3717 3718This is a configuration pragma which activates a mode in which speed is 3719considered more important for floating-point operations than absolutely 3720accurate adherence to the requirements of the standard. Currently the 3721following operations are affected: 3722 3723 3724@table @asis 3725 3726@item @emph{Complex Multiplication} 3727 3728The normal simple formula for complex multiplication can result in intermediate 3729overflows for numbers near the end of the range. The Ada standard requires that 3730this situation be detected and corrected by scaling, but in Fast_Math mode such 3731cases will simply result in overflow. Note that to take advantage of this you 3732must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 3733under control of the pragma, rather than use the preinstantiated versions. 3734@end table 3735 3736@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 3737@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{69}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6a} 3738@section Pragma Favor_Top_Level 3739 3740 3741Syntax: 3742 3743@example 3744pragma Favor_Top_Level (type_NAME); 3745@end example 3746 3747The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram 3748type. This pragma is an efficiency hint to the compiler, regarding the use of 3749@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. 3750The pragma means that nested subprograms are not used with this type, or are 3751rare, so that the generated code should be efficient in the top-level case. 3752When this pragma is used, dynamically generated trampolines may be used on some 3753targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. 3754 3755@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 3756@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6b} 3757@section Pragma Finalize_Storage_Only 3758 3759 3760Syntax: 3761 3762@example 3763pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3764@end example 3765 3766The argument of pragma @code{Finalize_Storage_Only} must denote a local type which 3767is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The 3768pragma suppresses the call to @code{Finalize} for declared library-level objects 3769of the argument type. This is mostly useful for types where finalization is 3770only used to deal with storage reclamation since in most environments it is 3771not necessary to reclaim memory just before terminating execution, hence the 3772name. Note that this pragma does not suppress Finalize calls for library-level 3773heap-allocated objects (see pragma @code{No_Heap_Finalization}). 3774 3775@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 3776@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6c} 3777@section Pragma Float_Representation 3778 3779 3780Syntax: 3781 3782@example 3783pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3784 3785FLOAT_REP ::= VAX_Float | IEEE_Float 3786@end example 3787 3788In the one argument form, this pragma is a configuration pragma which 3789allows control over the internal representation chosen for the predefined 3790floating point types declared in the packages @code{Standard} and 3791@code{System}. This pragma is only provided for compatibility and has no effect. 3792 3793The two argument form specifies the representation to be used for 3794the specified floating-point type. The argument must 3795be @code{IEEE_Float} to specify the use of IEEE format, as follows: 3796 3797 3798@itemize * 3799 3800@item 3801For a digits value of 6, 32-bit IEEE short format will be used. 3802 3803@item 3804For a digits value of 15, 64-bit IEEE long format will be used. 3805 3806@item 3807No other value of digits is permitted. 3808@end itemize 3809 3810@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 3811@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6d}@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6e} 3812@section Pragma Ghost 3813 3814 3815Syntax: 3816 3817@example 3818pragma Ghost [ (boolean_EXPRESSION) ]; 3819@end example 3820 3821For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK 38222014 Reference Manual, section 6.9. 3823 3824@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 3825@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{6f}@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{70} 3826@section Pragma Global 3827 3828 3829Syntax: 3830 3831@example 3832pragma Global (GLOBAL_SPECIFICATION); 3833 3834GLOBAL_SPECIFICATION ::= 3835 null 3836 | (GLOBAL_LIST) 3837 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 3838 3839MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 3840 3841MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 3842GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 3843GLOBAL_ITEM ::= NAME 3844@end example 3845 3846For the semantics of this pragma, see the entry for aspect @code{Global} in the 3847SPARK 2014 Reference Manual, section 6.1.4. 3848 3849@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 3850@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{71} 3851@section Pragma Ident 3852 3853 3854Syntax: 3855 3856@example 3857pragma Ident (static_string_EXPRESSION); 3858@end example 3859 3860This pragma is identical in effect to pragma @code{Comment}. It is provided 3861for compatibility with other Ada compilers providing this pragma. 3862 3863@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 3864@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{72} 3865@section Pragma Ignore_Pragma 3866 3867 3868Syntax: 3869 3870@example 3871pragma Ignore_Pragma (pragma_IDENTIFIER); 3872@end example 3873 3874This is a configuration pragma 3875that takes a single argument that is a simple identifier. Any subsequent 3876use of a pragma whose pragma identifier matches this argument will be 3877silently ignored. This may be useful when legacy code or code intended 3878for compilation with some other compiler contains pragmas that match the 3879name, but not the exact implementation, of a GNAT pragma. The use of this 3880pragma allows such pragmas to be ignored, which may be useful in CodePeer 3881mode, or during porting of legacy code. 3882 3883@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 3884@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{73} 3885@section Pragma Implementation_Defined 3886 3887 3888Syntax: 3889 3890@example 3891pragma Implementation_Defined (local_NAME); 3892@end example 3893 3894This pragma marks a previously declared entity as implementation-defined. 3895For an overloaded entity, applies to the most recent homonym. 3896 3897@example 3898pragma Implementation_Defined; 3899@end example 3900 3901The form with no arguments appears anywhere within a scope, most 3902typically a package spec, and indicates that all entities that are 3903defined within the package spec are Implementation_Defined. 3904 3905This pragma is used within the GNAT runtime library to identify 3906implementation-defined entities introduced in language-defined units, 3907for the purpose of implementing the No_Implementation_Identifiers 3908restriction. 3909 3910@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 3911@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{74} 3912@section Pragma Implemented 3913 3914 3915Syntax: 3916 3917@example 3918pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 3919 3920implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 3921@end example 3922 3923This is an Ada 2012 representation pragma which applies to protected, task 3924and synchronized interface primitives. The use of pragma Implemented provides 3925a way to impose a static requirement on the overriding operation by adhering 3926to one of the three implementation kinds: entry, protected procedure or any of 3927the above. This pragma is available in all earlier versions of Ada as an 3928implementation-defined pragma. 3929 3930@example 3931type Synch_Iface is synchronized interface; 3932procedure Prim_Op (Obj : in out Iface) is abstract; 3933pragma Implemented (Prim_Op, By_Protected_Procedure); 3934 3935protected type Prot_1 is new Synch_Iface with 3936 procedure Prim_Op; -- Legal 3937end Prot_1; 3938 3939protected type Prot_2 is new Synch_Iface with 3940 entry Prim_Op; -- Illegal 3941end Prot_2; 3942 3943task type Task_Typ is new Synch_Iface with 3944 entry Prim_Op; -- Illegal 3945end Task_Typ; 3946@end example 3947 3948When applied to the procedure_or_entry_NAME of a requeue statement, pragma 3949Implemented determines the runtime behavior of the requeue. Implementation kind 3950By_Entry guarantees that the action of requeueing will proceed from an entry to 3951another entry. Implementation kind By_Protected_Procedure transforms the 3952requeue into a dispatching call, thus eliminating the chance of blocking. Kind 3953By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 3954the target's overriding subprogram kind. 3955 3956@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 3957@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{75} 3958@section Pragma Implicit_Packing 3959 3960 3961@geindex Rational Profile 3962 3963Syntax: 3964 3965@example 3966pragma Implicit_Packing; 3967@end example 3968 3969This is a configuration pragma that requests implicit packing for packed 3970arrays for which a size clause is given but no explicit pragma Pack or 3971specification of Component_Size is present. It also applies to records 3972where no record representation clause is present. Consider this example: 3973 3974@example 3975type R is array (0 .. 7) of Boolean; 3976for R'Size use 8; 3977@end example 3978 3979In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 3980does not change the layout of a composite object. So the Size clause in the 3981above example is normally rejected, since the default layout of the array uses 39828-bit components, and thus the array requires a minimum of 64 bits. 3983 3984If this declaration is compiled in a region of code covered by an occurrence 3985of the configuration pragma Implicit_Packing, then the Size clause in this 3986and similar examples will cause implicit packing and thus be accepted. For 3987this implicit packing to occur, the type in question must be an array of small 3988components whose size is known at compile time, and the Size clause must 3989specify the exact size that corresponds to the number of elements in the array 3990multiplied by the size in bits of the component type (both single and 3991multi-dimensioned arrays can be controlled with this pragma). 3992 3993@geindex Array packing 3994 3995Similarly, the following example shows the use in the record case 3996 3997@example 3998type r is record 3999 a, b, c, d, e, f, g, h : boolean; 4000 chr : character; 4001end record; 4002for r'size use 16; 4003@end example 4004 4005Without a pragma Pack, each Boolean field requires 8 bits, so the 4006minimum size is 72 bits, but with a pragma Pack, 16 bits would be 4007sufficient. The use of pragma Implicit_Packing allows this record 4008declaration to compile without an explicit pragma Pack. 4009 4010@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 4011@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{76} 4012@section Pragma Import_Function 4013 4014 4015Syntax: 4016 4017@example 4018pragma Import_Function ( 4019 [Internal =>] LOCAL_NAME, 4020 [, [External =>] EXTERNAL_SYMBOL] 4021 [, [Parameter_Types =>] PARAMETER_TYPES] 4022 [, [Result_Type =>] SUBTYPE_MARK] 4023 [, [Mechanism =>] MECHANISM] 4024 [, [Result_Mechanism =>] MECHANISM_NAME]); 4025 4026EXTERNAL_SYMBOL ::= 4027 IDENTIFIER 4028| static_string_EXPRESSION 4029 4030PARAMETER_TYPES ::= 4031 null 4032| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4033 4034TYPE_DESIGNATOR ::= 4035 subtype_NAME 4036| subtype_Name ' Access 4037 4038MECHANISM ::= 4039 MECHANISM_NAME 4040| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4041 4042MECHANISM_ASSOCIATION ::= 4043 [formal_parameter_NAME =>] MECHANISM_NAME 4044 4045MECHANISM_NAME ::= 4046 Value 4047| Reference 4048@end example 4049 4050This pragma is used in conjunction with a pragma @code{Import} to 4051specify additional information for an imported function. The pragma 4052@code{Import} (or equivalent pragma @code{Interface}) must precede the 4053@code{Import_Function} pragma and both must appear in the same 4054declarative part as the function specification. 4055 4056The @code{Internal} argument must uniquely designate 4057the function to which the 4058pragma applies. If more than one function name exists of this name in 4059the declarative part you must use the @code{Parameter_Types} and 4060@code{Result_Type} parameters to achieve the required unique 4061designation. Subtype marks in these parameters must exactly match the 4062subtypes in the corresponding function specification, using positional 4063notation to match parameters with subtype marks. 4064The form with an @code{'Access} attribute can be used to match an 4065anonymous access parameter. 4066 4067You may optionally use the @code{Mechanism} and @code{Result_Mechanism} 4068parameters to specify passing mechanisms for the 4069parameters and result. If you specify a single mechanism name, it 4070applies to all parameters. Otherwise you may specify a mechanism on a 4071parameter by parameter basis using either positional or named 4072notation. If the mechanism is not specified, the default mechanism 4073is used. 4074 4075@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 4076@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{77} 4077@section Pragma Import_Object 4078 4079 4080Syntax: 4081 4082@example 4083pragma Import_Object 4084 [Internal =>] LOCAL_NAME 4085 [, [External =>] EXTERNAL_SYMBOL] 4086 [, [Size =>] EXTERNAL_SYMBOL]); 4087 4088EXTERNAL_SYMBOL ::= 4089 IDENTIFIER 4090| static_string_EXPRESSION 4091@end example 4092 4093This pragma designates an object as imported, and apart from the 4094extended rules for external symbols, is identical in effect to the use of 4095the normal @code{Import} pragma applied to an object. Unlike the 4096subprogram case, you need not use a separate @code{Import} pragma, 4097although you may do so (and probably should do so from a portability 4098point of view). @code{size} is syntax checked, but otherwise ignored by 4099GNAT. 4100 4101@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 4102@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{78} 4103@section Pragma Import_Procedure 4104 4105 4106Syntax: 4107 4108@example 4109pragma Import_Procedure ( 4110 [Internal =>] LOCAL_NAME 4111 [, [External =>] EXTERNAL_SYMBOL] 4112 [, [Parameter_Types =>] PARAMETER_TYPES] 4113 [, [Mechanism =>] MECHANISM]); 4114 4115EXTERNAL_SYMBOL ::= 4116 IDENTIFIER 4117| static_string_EXPRESSION 4118 4119PARAMETER_TYPES ::= 4120 null 4121| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4122 4123TYPE_DESIGNATOR ::= 4124 subtype_NAME 4125| subtype_Name ' Access 4126 4127MECHANISM ::= 4128 MECHANISM_NAME 4129| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4130 4131MECHANISM_ASSOCIATION ::= 4132 [formal_parameter_NAME =>] MECHANISM_NAME 4133 4134MECHANISM_NAME ::= Value | Reference 4135@end example 4136 4137This pragma is identical to @code{Import_Function} except that it 4138applies to a procedure rather than a function and the parameters 4139@code{Result_Type} and @code{Result_Mechanism} are not permitted. 4140 4141@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4142@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{79} 4143@section Pragma Import_Valued_Procedure 4144 4145 4146Syntax: 4147 4148@example 4149pragma Import_Valued_Procedure ( 4150 [Internal =>] LOCAL_NAME 4151 [, [External =>] EXTERNAL_SYMBOL] 4152 [, [Parameter_Types =>] PARAMETER_TYPES] 4153 [, [Mechanism =>] MECHANISM]); 4154 4155EXTERNAL_SYMBOL ::= 4156 IDENTIFIER 4157| static_string_EXPRESSION 4158 4159PARAMETER_TYPES ::= 4160 null 4161| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4162 4163TYPE_DESIGNATOR ::= 4164 subtype_NAME 4165| subtype_Name ' Access 4166 4167MECHANISM ::= 4168 MECHANISM_NAME 4169| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4170 4171MECHANISM_ASSOCIATION ::= 4172 [formal_parameter_NAME =>] MECHANISM_NAME 4173 4174MECHANISM_NAME ::= Value | Reference 4175@end example 4176 4177This pragma is identical to @code{Import_Procedure} except that the 4178first parameter of @code{LOCAL_NAME}, which must be present, must be of 4179mode @code{out}, and externally the subprogram is treated as a function 4180with this parameter as the result of the function. The purpose of this 4181capability is to allow the use of @code{out} and @code{in out} 4182parameters in interfacing to external functions (which are not permitted 4183in Ada functions). You may optionally use the @code{Mechanism} 4184parameters to specify passing mechanisms for the parameters. 4185If you specify a single mechanism name, it applies to all parameters. 4186Otherwise you may specify a mechanism on a parameter by parameter 4187basis using either positional or named notation. If the mechanism is not 4188specified, the default mechanism is used. 4189 4190Note that it is important to use this pragma in conjunction with a separate 4191pragma Import that specifies the desired convention, since otherwise the 4192default convention is Ada, which is almost certainly not what is required. 4193 4194@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4195@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7a} 4196@section Pragma Independent 4197 4198 4199Syntax: 4200 4201@example 4202pragma Independent (Local_NAME); 4203@end example 4204 4205This pragma is standard in Ada 2012 mode (which also provides an aspect 4206of the same name). It is also available as an implementation-defined 4207pragma in all earlier versions. It specifies that the 4208designated object or all objects of the designated type must be 4209independently addressable. This means that separate tasks can safely 4210manipulate such objects. For example, if two components of a record are 4211independent, then two separate tasks may access these two components. 4212This may place 4213constraints on the representation of the object (for instance prohibiting 4214tight packing). 4215 4216@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4217@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7b} 4218@section Pragma Independent_Components 4219 4220 4221Syntax: 4222 4223@example 4224pragma Independent_Components (Local_NAME); 4225@end example 4226 4227This pragma is standard in Ada 2012 mode (which also provides an aspect 4228of the same name). It is also available as an implementation-defined 4229pragma in all earlier versions. It specifies that the components of the 4230designated object, or the components of each object of the designated 4231type, must be 4232independently addressable. This means that separate tasks can safely 4233manipulate separate components in the composite object. This may place 4234constraints on the representation of the object (for instance prohibiting 4235tight packing). 4236 4237@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4238@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7c}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7d} 4239@section Pragma Initial_Condition 4240 4241 4242Syntax: 4243 4244@example 4245pragma Initial_Condition (boolean_EXPRESSION); 4246@end example 4247 4248For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} 4249in the SPARK 2014 Reference Manual, section 7.1.6. 4250 4251@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4252@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{7e} 4253@section Pragma Initialize_Scalars 4254 4255 4256@geindex debugging with Initialize_Scalars 4257 4258Syntax: 4259 4260@example 4261pragma Initialize_Scalars; 4262@end example 4263 4264This pragma is similar to @code{Normalize_Scalars} conceptually but has 4265two important differences. First, there is no requirement for the pragma 4266to be used uniformly in all units of a partition, in particular, it is fine 4267to use this just for some or all of the application units of a partition, 4268without needing to recompile the run-time library. 4269 4270In the case where some units are compiled with the pragma, and some without, 4271then a declaration of a variable where the type is defined in package 4272Standard or is locally declared will always be subject to initialization, 4273as will any declaration of a scalar variable. For composite variables, 4274whether the variable is initialized may also depend on whether the package 4275in which the type of the variable is declared is compiled with the pragma. 4276 4277The other important difference is that you can control the value used 4278for initializing scalar objects. At bind time, you can select several 4279options for initialization. You can 4280initialize with invalid values (similar to Normalize_Scalars, though for 4281Initialize_Scalars it is not always possible to determine the invalid 4282values in complex cases like signed component fields with non-standard 4283sizes). You can also initialize with high or 4284low values, or with a specified bit pattern. See the GNAT 4285User's Guide for binder options for specifying these cases. 4286 4287This means that you can compile a program, and then without having to 4288recompile the program, you can run it with different values being used 4289for initializing otherwise uninitialized values, to test if your program 4290behavior depends on the choice. Of course the behavior should not change, 4291and if it does, then most likely you have an incorrect reference to an 4292uninitialized value. 4293 4294It is even possible to change the value at execution time eliminating even 4295the need to rebind with a different switch using an environment variable. 4296See the GNAT User's Guide for details. 4297 4298Note that pragma @code{Initialize_Scalars} is particularly useful in 4299conjunction with the enhanced validity checking that is now provided 4300in GNAT, which checks for invalid values under more conditions. 4301Using this feature (see description of the @emph{-gnatV} flag in the 4302GNAT User's Guide) in conjunction with 4303pragma @code{Initialize_Scalars} 4304provides a powerful new tool to assist in the detection of problems 4305caused by uninitialized variables. 4306 4307Note: the use of @code{Initialize_Scalars} has a fairly extensive 4308effect on the generated code. This may cause your code to be 4309substantially larger. It may also cause an increase in the amount 4310of stack required, so it is probably a good idea to turn on stack 4311checking (see description of stack checking in the GNAT 4312User's Guide) when using this pragma. 4313 4314@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4315@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{7f}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80} 4316@section Pragma Initializes 4317 4318 4319Syntax: 4320 4321@example 4322pragma Initializes (INITIALIZATION_LIST); 4323 4324INITIALIZATION_LIST ::= 4325 null 4326 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4327 4328INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4329 4330INPUT_LIST ::= 4331 null 4332 | INPUT 4333 | (INPUT @{, INPUT@}) 4334 4335INPUT ::= name 4336@end example 4337 4338For the semantics of this pragma, see the entry for aspect @code{Initializes} in the 4339SPARK 2014 Reference Manual, section 7.1.5. 4340 4341@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4342@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{82} 4343@section Pragma Inline_Always 4344 4345 4346Syntax: 4347 4348@example 4349pragma Inline_Always (NAME [, NAME]); 4350@end example 4351 4352Similar to pragma @code{Inline} except that inlining is unconditional. 4353Inline_Always instructs the compiler to inline every direct call to the 4354subprogram or else to emit a compilation error, independently of any 4355option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. 4356It is an error to take the address or access of @code{NAME}. It is also an error to 4357apply this pragma to a primitive operation of a tagged type. Thanks to such 4358restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. 4359 4360@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4361@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{83} 4362@section Pragma Inline_Generic 4363 4364 4365Syntax: 4366 4367@example 4368pragma Inline_Generic (GNAME @{, GNAME@}); 4369 4370GNAME ::= generic_unit_NAME | generic_instance_NAME 4371@end example 4372 4373This pragma is provided for compatibility with Dec Ada 83. It has 4374no effect in GNAT (which always inlines generics), other 4375than to check that the given names are all names of generic units or 4376generic instances. 4377 4378@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4379@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{84} 4380@section Pragma Interface 4381 4382 4383Syntax: 4384 4385@example 4386pragma Interface ( 4387 [Convention =>] convention_identifier, 4388 [Entity =>] local_NAME 4389 [, [External_Name =>] static_string_expression] 4390 [, [Link_Name =>] static_string_expression]); 4391@end example 4392 4393This pragma is identical in syntax and semantics to 4394the standard Ada pragma @code{Import}. It is provided for compatibility 4395with Ada 83. The definition is upwards compatible both with pragma 4396@code{Interface} as defined in the Ada 83 Reference Manual, and also 4397with some extended implementations of this pragma in certain Ada 83 4398implementations. The only difference between pragma @code{Interface} 4399and pragma @code{Import} is that there is special circuitry to allow 4400both pragmas to appear for the same subprogram entity (normally it 4401is illegal to have multiple @code{Import} pragmas. This is useful in 4402maintaining Ada 83/Ada 95 compatibility and is compatible with other 4403Ada 83 compilers. 4404 4405@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4406@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{85} 4407@section Pragma Interface_Name 4408 4409 4410Syntax: 4411 4412@example 4413pragma Interface_Name ( 4414 [Entity =>] LOCAL_NAME 4415 [, [External_Name =>] static_string_EXPRESSION] 4416 [, [Link_Name =>] static_string_EXPRESSION]); 4417@end example 4418 4419This pragma provides an alternative way of specifying the interface name 4420for an interfaced subprogram, and is provided for compatibility with Ada 442183 compilers that use the pragma for this purpose. You must provide at 4422least one of @code{External_Name} or @code{Link_Name}. 4423 4424@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4425@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{86} 4426@section Pragma Interrupt_Handler 4427 4428 4429Syntax: 4430 4431@example 4432pragma Interrupt_Handler (procedure_LOCAL_NAME); 4433@end example 4434 4435This program unit pragma is supported for parameterless protected procedures 4436as described in Annex C of the Ada Reference Manual. On the AAMP target 4437the pragma can also be specified for nonprotected parameterless procedures 4438that are declared at the library level (which includes procedures 4439declared at the top level of a library package). In the case of AAMP, 4440when this pragma is applied to a nonprotected procedure, the instruction 4441@code{IERET} is generated for returns from the procedure, enabling 4442maskable interrupts, in place of the normal return instruction. 4443 4444@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4445@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{87} 4446@section Pragma Interrupt_State 4447 4448 4449Syntax: 4450 4451@example 4452pragma Interrupt_State 4453 ([Name =>] value, 4454 [State =>] SYSTEM | RUNTIME | USER); 4455@end example 4456 4457Normally certain interrupts are reserved to the implementation. Any attempt 4458to attach an interrupt causes Program_Error to be raised, as described in 4459RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 4460many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4461reserved to the implementation, so that @code{Ctrl-C} can be used to 4462interrupt execution. Additionally, signals such as @code{SIGSEGV}, 4463@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 4464Ada exceptions, or used to implement run-time functions such as the 4465@code{abort} statement and stack overflow checking. 4466 4467Pragma @code{Interrupt_State} provides a general mechanism for overriding 4468such uses of interrupts. It subsumes the functionality of pragma 4469@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 4470available on Windows or VMS. On all other platforms than VxWorks, 4471it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4472and may be used to mark interrupts required by the board support package 4473as reserved. 4474 4475Interrupts can be in one of three states: 4476 4477 4478@itemize * 4479 4480@item 4481System 4482 4483The interrupt is reserved (no Ada handler can be installed), and the 4484Ada run-time may not install a handler. As a result you are guaranteed 4485standard system default action if this interrupt is raised. This also allows 4486installing a low level handler via C APIs such as sigaction(), outside 4487of Ada control. 4488 4489@item 4490Runtime 4491 4492The interrupt is reserved (no Ada handler can be installed). The run time 4493is allowed to install a handler for internal control purposes, but is 4494not required to do so. 4495 4496@item 4497User 4498 4499The interrupt is unreserved. The user may install an Ada handler via 4500Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 4501some other action. 4502@end itemize 4503 4504These states are the allowed values of the @code{State} parameter of the 4505pragma. The @code{Name} parameter is a value of the type 4506@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4507@code{Ada.Interrupts.Names}. 4508 4509This is a configuration pragma, and the binder will check that there 4510are no inconsistencies between different units in a partition in how a 4511given interrupt is specified. It may appear anywhere a pragma is legal. 4512 4513The effect is to move the interrupt to the specified state. 4514 4515By declaring interrupts to be SYSTEM, you guarantee the standard system 4516action, such as a core dump. 4517 4518By declaring interrupts to be USER, you guarantee that you can install 4519a handler. 4520 4521Note that certain signals on many operating systems cannot be caught and 4522handled by applications. In such cases, the pragma is ignored. See the 4523operating system documentation, or the value of the array @code{Reserved} 4524declared in the spec of package @code{System.OS_Interface}. 4525 4526Overriding the default state of signals used by the Ada runtime may interfere 4527with an application's runtime behavior in the cases of the synchronous signals, 4528and in the case of the signal used to implement the @code{abort} statement. 4529 4530@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4531@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{88}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{89} 4532@section Pragma Invariant 4533 4534 4535Syntax: 4536 4537@example 4538pragma Invariant 4539 ([Entity =>] private_type_LOCAL_NAME, 4540 [Check =>] EXPRESSION 4541 [,[Message =>] String_Expression]); 4542@end example 4543 4544This pragma provides exactly the same capabilities as the Type_Invariant aspect 4545defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4546Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4547requires the use of the aspect syntax, which is not available except in 2012 4548mode, it is not possible to use the Type_Invariant aspect in earlier versions 4549of Ada. However the Invariant pragma may be used in any version of Ada. Also 4550note that the aspect Invariant is a synonym in GNAT for the aspect 4551Type_Invariant, but there is no pragma Type_Invariant. 4552 4553The pragma must appear within the visible part of the package specification, 4554after the type to which its Entity argument appears. As with the Invariant 4555aspect, the Check expression is not analyzed until the end of the visible 4556part of the package, so it may contain forward references. The Message 4557argument, if present, provides the exception message used if the invariant 4558is violated. If no Message parameter is provided, a default message that 4559identifies the line on which the pragma appears is used. 4560 4561It is permissible to have multiple Invariants for the same type entity, in 4562which case they are and'ed together. It is permissible to use this pragma 4563in Ada 2012 mode, but you cannot have both an invariant aspect and an 4564invariant pragma for the same entity. 4565 4566For further details on the use of this pragma, see the Ada 2012 documentation 4567of the Type_Invariant aspect. 4568 4569@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4570@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8a} 4571@section Pragma Keep_Names 4572 4573 4574Syntax: 4575 4576@example 4577pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4578@end example 4579 4580The @code{LOCAL_NAME} argument 4581must refer to an enumeration first subtype 4582in the current declarative part. The effect is to retain the enumeration 4583literal names for use by @code{Image} and @code{Value} even if a global 4584@code{Discard_Names} pragma applies. This is useful when you want to 4585generally suppress enumeration literal names and for example you therefore 4586use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you 4587want to retain the names for specific enumeration types. 4588 4589@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4590@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8b} 4591@section Pragma License 4592 4593 4594@geindex License checking 4595 4596Syntax: 4597 4598@example 4599pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4600@end example 4601 4602This pragma is provided to allow automated checking for appropriate license 4603conditions with respect to the standard and modified GPL. A pragma 4604@code{License}, which is a configuration pragma that typically appears at 4605the start of a source file or in a separate @code{gnat.adc} file, specifies 4606the licensing conditions of a unit as follows: 4607 4608 4609@itemize * 4610 4611@item 4612Unrestricted 4613This is used for a unit that can be freely used with no license restrictions. 4614Examples of such units are public domain units, and units from the Ada 4615Reference Manual. 4616 4617@item 4618GPL 4619This is used for a unit that is licensed under the unmodified GPL, and which 4620therefore cannot be @code{with}ed by a restricted unit. 4621 4622@item 4623Modified_GPL 4624This is used for a unit licensed under the GNAT modified GPL that includes 4625a special exception paragraph that specifically permits the inclusion of 4626the unit in programs without requiring the entire program to be released 4627under the GPL. 4628 4629@item 4630Restricted 4631This is used for a unit that is restricted in that it is not permitted to 4632depend on units that are licensed under the GPL. Typical examples are 4633proprietary code that is to be released under more restrictive license 4634conditions. Note that restricted units are permitted to @code{with} units 4635which are licensed under the modified GPL (this is the whole point of the 4636modified GPL). 4637@end itemize 4638 4639Normally a unit with no @code{License} pragma is considered to have an 4640unknown license, and no checking is done. However, standard GNAT headers 4641are recognized, and license information is derived from them as follows. 4642 4643A GNAT license header starts with a line containing 78 hyphens. The following 4644comment text is searched for the appearance of any of the following strings. 4645 4646If the string 'GNU General Public License' is found, then the unit is assumed 4647to have GPL license, unless the string 'As a special exception' follows, in 4648which case the license is assumed to be modified GPL. 4649 4650If one of the strings 4651'This specification is adapted from the Ada Semantic Interface' or 4652'This specification is derived from the Ada Reference Manual' is found 4653then the unit is assumed to be unrestricted. 4654 4655These default actions means that a program with a restricted license pragma 4656will automatically get warnings if a GPL unit is inappropriately 4657@code{with}ed. For example, the program: 4658 4659@example 4660with Sem_Ch3; 4661with GNAT.Sockets; 4662procedure Secret_Stuff is 4663 ... 4664end Secret_Stuff 4665@end example 4666 4667if compiled with pragma @code{License} (@code{Restricted}) in a 4668@code{gnat.adc} file will generate the warning: 4669 4670@example 46711. with Sem_Ch3; 4672 | 4673 >>> license of withed unit "Sem_Ch3" is incompatible 4674 46752. with GNAT.Sockets; 46763. procedure Secret_Stuff is 4677@end example 4678 4679Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 4680compiler and is licensed under the 4681GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 4682run time, and is therefore licensed under the modified GPL. 4683 4684@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 4685@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8c} 4686@section Pragma Link_With 4687 4688 4689Syntax: 4690 4691@example 4692pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4693@end example 4694 4695This pragma is provided for compatibility with certain Ada 83 compilers. 4696It has exactly the same effect as pragma @code{Linker_Options} except 4697that spaces occurring within one of the string expressions are treated 4698as separators. For example, in the following case: 4699 4700@example 4701pragma Link_With ("-labc -ldef"); 4702@end example 4703 4704results in passing the strings @code{-labc} and @code{-ldef} as two 4705separate arguments to the linker. In addition pragma Link_With allows 4706multiple arguments, with the same effect as successive pragmas. 4707 4708@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 4709@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8d} 4710@section Pragma Linker_Alias 4711 4712 4713Syntax: 4714 4715@example 4716pragma Linker_Alias ( 4717 [Entity =>] LOCAL_NAME, 4718 [Target =>] static_string_EXPRESSION); 4719@end example 4720 4721@code{LOCAL_NAME} must refer to an object that is declared at the library 4722level. This pragma establishes the given entity as a linker alias for the 4723given target. It is equivalent to @code{__attribute__((alias))} in GNU C 4724and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol 4725@code{static_string_EXPRESSION} in the object file, that is to say no space 4726is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved 4727to the same address as @code{static_string_EXPRESSION} by the linker. 4728 4729The actual linker name for the target must be used (e.g., the fully 4730encoded name with qualification in Ada, or the mangled name in C++), 4731or it must be declared using the C convention with @code{pragma Import} 4732or @code{pragma Export}. 4733 4734Not all target machines support this pragma. On some of them it is accepted 4735only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. 4736 4737@example 4738-- Example of the use of pragma Linker_Alias 4739 4740package p is 4741 i : Integer := 1; 4742 pragma Export (C, i); 4743 4744 new_name_for_i : Integer; 4745 pragma Linker_Alias (new_name_for_i, "i"); 4746end p; 4747@end example 4748 4749@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 4750@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{8e} 4751@section Pragma Linker_Constructor 4752 4753 4754Syntax: 4755 4756@example 4757pragma Linker_Constructor (procedure_LOCAL_NAME); 4758@end example 4759 4760@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4761is declared at the library level. A procedure to which this pragma is 4762applied will be treated as an initialization routine by the linker. 4763It is equivalent to @code{__attribute__((constructor))} in GNU C and 4764causes @code{procedure_LOCAL_NAME} to be invoked before the entry point 4765of the executable is called (or immediately after the shared library is 4766loaded if the procedure is linked in a shared library), in particular 4767before the Ada run-time environment is set up. 4768 4769Because of these specific contexts, the set of operations such a procedure 4770can perform is very limited and the type of objects it can manipulate is 4771essentially restricted to the elementary types. In particular, it must only 4772contain code to which pragma Restrictions (No_Elaboration_Code) applies. 4773 4774This pragma is used by GNAT to implement auto-initialization of shared Stand 4775Alone Libraries, which provides a related capability without the restrictions 4776listed above. Where possible, the use of Stand Alone Libraries is preferable 4777to the use of this pragma. 4778 4779@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 4780@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{8f} 4781@section Pragma Linker_Destructor 4782 4783 4784Syntax: 4785 4786@example 4787pragma Linker_Destructor (procedure_LOCAL_NAME); 4788@end example 4789 4790@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4791is declared at the library level. A procedure to which this pragma is 4792applied will be treated as a finalization routine by the linker. 4793It is equivalent to @code{__attribute__((destructor))} in GNU C and 4794causes @code{procedure_LOCAL_NAME} to be invoked after the entry point 4795of the executable has exited (or immediately before the shared library 4796is unloaded if the procedure is linked in a shared library), in particular 4797after the Ada run-time environment is shut down. 4798 4799See @code{pragma Linker_Constructor} for the set of restrictions that apply 4800because of these specific contexts. 4801 4802@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 4803@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{90}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{91} 4804@section Pragma Linker_Section 4805 4806 4807Syntax: 4808 4809@example 4810pragma Linker_Section ( 4811 [Entity =>] LOCAL_NAME, 4812 [Section =>] static_string_EXPRESSION); 4813@end example 4814 4815@code{LOCAL_NAME} must refer to an object, type, or subprogram that is 4816declared at the library level. This pragma specifies the name of the 4817linker section for the given entity. It is equivalent to 4818@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to 4819be placed in the @code{static_string_EXPRESSION} section of the 4820executable (assuming the linker doesn't rename the section). 4821GNAT also provides an implementation defined aspect of the same name. 4822 4823In the case of specifying this aspect for a type, the effect is to 4824specify the corresponding section for all library-level objects of 4825the type that do not have an explicit linker section set. Note that 4826this only applies to whole objects, not to components of composite objects. 4827 4828In the case of a subprogram, the linker section applies to all previously 4829declared matching overloaded subprograms in the current declarative part 4830which do not already have a linker section assigned. The linker section 4831aspect is useful in this case for specifying different linker sections 4832for different elements of such an overloaded set. 4833 4834Note that an empty string specifies that no linker section is specified. 4835This is not quite the same as omitting the pragma or aspect, since it 4836can be used to specify that one element of an overloaded set of subprograms 4837has the default linker section, or that one object of a type for which a 4838linker section is specified should has the default linker section. 4839 4840The compiler normally places library-level entities in standard sections 4841depending on the class: procedures and functions generally go in the 4842@code{.text} section, initialized variables in the @code{.data} section 4843and uninitialized variables in the @code{.bss} section. 4844 4845Other, special sections may exist on given target machines to map special 4846hardware, for example I/O ports or flash memory. This pragma is a means to 4847defer the final layout of the executable to the linker, thus fully working 4848at the symbolic level with the compiler. 4849 4850Some file formats do not support arbitrary sections so not all target 4851machines support this pragma. The use of this pragma may cause a program 4852execution to be erroneous if it is used to place an entity into an 4853inappropriate section (e.g., a modified variable into the @code{.text} 4854section). See also @code{pragma Persistent_BSS}. 4855 4856@example 4857-- Example of the use of pragma Linker_Section 4858 4859package IO_Card is 4860 Port_A : Integer; 4861 pragma Volatile (Port_A); 4862 pragma Linker_Section (Port_A, ".bss.port_a"); 4863 4864 Port_B : Integer; 4865 pragma Volatile (Port_B); 4866 pragma Linker_Section (Port_B, ".bss.port_b"); 4867 4868 type Port_Type is new Integer with Linker_Section => ".bss"; 4869 PA : Port_Type with Linker_Section => ".bss.PA"; 4870 PB : Port_Type; -- ends up in linker section ".bss" 4871 4872 procedure Q with Linker_Section => "Qsection"; 4873end IO_Card; 4874@end example 4875 4876@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 4877@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{92}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{93} 4878@section Pragma Lock_Free 4879 4880 4881Syntax: 4882This pragma may be specified for protected types or objects. It specifies that 4883the implementation of protected operations must be implemented without locks. 4884Compilation fails if the compiler cannot generate lock-free code for the 4885operations. 4886 4887@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 4888@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{94} 4889@section Pragma Loop_Invariant 4890 4891 4892Syntax: 4893 4894@example 4895pragma Loop_Invariant ( boolean_EXPRESSION ); 4896@end example 4897 4898The effect of this pragma is similar to that of pragma @code{Assert}, 4899except that in an @code{Assertion_Policy} pragma, the identifier 4900@code{Loop_Invariant} is used to control whether it is ignored or checked 4901(or disabled). 4902 4903@code{Loop_Invariant} can only appear as one of the items in the sequence 4904of statements of a loop body, or nested inside block statements that 4905appear in the sequence of statements of a loop body. 4906The intention is that it be used to 4907represent a "loop invariant" assertion, i.e. something that is true each 4908time through the loop, and which can be used to show that the loop is 4909achieving its purpose. 4910 4911Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 4912apply to the same loop should be grouped in the same sequence of 4913statements. 4914 4915To aid in writing such invariants, the special attribute @code{Loop_Entry} 4916may be used to refer to the value of an expression on entry to the loop. This 4917attribute can only be used within the expression of a @code{Loop_Invariant} 4918pragma. For full details, see documentation of attribute @code{Loop_Entry}. 4919 4920@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 4921@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{95} 4922@section Pragma Loop_Optimize 4923 4924 4925Syntax: 4926 4927@example 4928pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 4929 4930OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 4931@end example 4932 4933This pragma must appear immediately within a loop statement. It allows the 4934programmer to specify optimization hints for the enclosing loop. The hints 4935are not mutually exclusive and can be freely mixed, but not all combinations 4936will yield a sensible outcome. 4937 4938There are five supported optimization hints for a loop: 4939 4940 4941@itemize * 4942 4943@item 4944Ivdep 4945 4946The programmer asserts that there are no loop-carried dependencies 4947which would prevent consecutive iterations of the loop from being 4948executed simultaneously. 4949 4950@item 4951No_Unroll 4952 4953The loop must not be unrolled. This is a strong hint: the compiler will not 4954unroll a loop marked with this hint. 4955 4956@item 4957Unroll 4958 4959The loop should be unrolled. This is a weak hint: the compiler will try to 4960apply unrolling to this loop preferably to other optimizations, notably 4961vectorization, but there is no guarantee that the loop will be unrolled. 4962 4963@item 4964No_Vector 4965 4966The loop must not be vectorized. This is a strong hint: the compiler will not 4967vectorize a loop marked with this hint. 4968 4969@item 4970Vector 4971 4972The loop should be vectorized. This is a weak hint: the compiler will try to 4973apply vectorization to this loop preferably to other optimizations, notably 4974unrolling, but there is no guarantee that the loop will be vectorized. 4975@end itemize 4976 4977These hints do not remove the need to pass the appropriate switches to the 4978compiler in order to enable the relevant optimizations, that is to say 4979@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 4980vectorization. 4981 4982@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 4983@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{96} 4984@section Pragma Loop_Variant 4985 4986 4987Syntax: 4988 4989@example 4990pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 4991LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 4992CHANGE_DIRECTION ::= Increases | Decreases 4993@end example 4994 4995@code{Loop_Variant} can only appear as one of the items in the sequence 4996of statements of a loop body, or nested inside block statements that 4997appear in the sequence of statements of a loop body. 4998It allows the specification of quantities which must always 4999decrease or increase in successive iterations of the loop. In its simplest 5000form, just one expression is specified, whose value must increase or decrease 5001on each iteration of the loop. 5002 5003In a more complex form, multiple arguments can be given which are intepreted 5004in a nesting lexicographic manner. For example: 5005 5006@example 5007pragma Loop_Variant (Increases => X, Decreases => Y); 5008@end example 5009 5010specifies that each time through the loop either X increases, or X stays 5011the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 5012loop is making progress. It can be useful in helping to show informally 5013or prove formally that the loop always terminates. 5014 5015@code{Loop_Variant} is an assertion whose effect can be controlled using 5016an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 5017policy can be @code{Check} to enable the loop variant check, @code{Ignore} 5018to ignore the check (in which case the pragma has no effect on the program), 5019or @code{Disable} in which case the pragma is not even checked for correct 5020syntax. 5021 5022Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5023apply to the same loop should be grouped in the same sequence of 5024statements. 5025 5026The @code{Loop_Entry} attribute may be used within the expressions of the 5027@code{Loop_Variant} pragma to refer to values on entry to the loop. 5028 5029@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 5030@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{97} 5031@section Pragma Machine_Attribute 5032 5033 5034Syntax: 5035 5036@example 5037pragma Machine_Attribute ( 5038 [Entity =>] LOCAL_NAME, 5039 [Attribute_Name =>] static_string_EXPRESSION 5040 [, [Info =>] static_EXPRESSION] ); 5041@end example 5042 5043Machine-dependent attributes can be specified for types and/or 5044declarations. This pragma is semantically equivalent to 5045@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not 5046specified) or @code{__attribute__((@emph{attribute_name(info})))} 5047in GNU C, where @emph{attribute_name} is recognized by the 5048compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine 5049specific macro. A string literal for the optional parameter @code{info} 5050is transformed into an identifier, which may make this pragma unusable 5051for some attributes. 5052For further information see @cite{GNU Compiler Collection (GCC) Internals}. 5053 5054@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 5055@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{98} 5056@section Pragma Main 5057 5058 5059Syntax: 5060 5061@example 5062pragma Main 5063 (MAIN_OPTION [, MAIN_OPTION]); 5064 5065MAIN_OPTION ::= 5066 [Stack_Size =>] static_integer_EXPRESSION 5067| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 5068| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 5069@end example 5070 5071This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5072no effect in GNAT, other than being syntax checked. 5073 5074@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas 5075@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{99} 5076@section Pragma Main_Storage 5077 5078 5079Syntax: 5080 5081@example 5082pragma Main_Storage 5083 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 5084 5085MAIN_STORAGE_OPTION ::= 5086 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 5087| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 5088@end example 5089 5090This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5091no effect in GNAT, other than being syntax checked. 5092 5093@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas 5094@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9a}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9b} 5095@section Pragma Max_Queue_Length 5096 5097 5098Syntax: 5099 5100@example 5101pragma Max_Entry_Queue (static_integer_EXPRESSION); 5102@end example 5103 5104This pragma is used to specify the maximum callers per entry queue for 5105individual protected entries and entry families. It accepts a single 5106positive integer as a parameter and must appear after the declaration 5107of an entry. 5108 5109@node Pragma No_Body,Pragma No_Component_Reordering,Pragma Max_Queue_Length,Implementation Defined Pragmas 5110@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9c} 5111@section Pragma No_Body 5112 5113 5114Syntax: 5115 5116@example 5117pragma No_Body; 5118@end example 5119 5120There are a number of cases in which a package spec does not require a body, 5121and in fact a body is not permitted. GNAT will not permit the spec to be 5122compiled if there is a body around. The pragma No_Body allows you to provide 5123a body file, even in a case where no body is allowed. The body file must 5124contain only comments and a single No_Body pragma. This is recognized by 5125the compiler as indicating that no body is logically present. 5126 5127This is particularly useful during maintenance when a package is modified in 5128such a way that a body needed before is no longer needed. The provision of a 5129dummy body with a No_Body pragma ensures that there is no interference from 5130earlier versions of the package body. 5131 5132@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Body,Implementation Defined Pragmas 5133@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{9d} 5134@section Pragma No_Component_Reordering 5135 5136 5137Syntax: 5138 5139@example 5140pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 5141@end example 5142 5143@code{type_LOCAL_NAME} must refer to a record type declaration in the current 5144declarative part. The effect is to preclude any reordering of components 5145for the layout of the record, i.e. the record is laid out by the compiler 5146in the order in which the components are declared textually. The form with 5147no argument is a configuration pragma which applies to all record types 5148declared in units to which the pragma applies and there is a requirement 5149that this pragma be used consistently within a partition. 5150 5151@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas 5152@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{9f} 5153@section Pragma No_Elaboration_Code_All 5154 5155 5156Syntax: 5157 5158@example 5159pragma No_Elaboration_Code_All [(program_unit_NAME)]; 5160@end example 5161 5162This is a program unit pragma (there is also an equivalent aspect of the 5163same name) that establishes the restriction @code{No_Elaboration_Code} for 5164the current unit and any extended main source units (body and subunits). 5165It also has the effect of enforcing a transitive application of this 5166aspect, so that if any unit is implicitly or explicitly with'ed by the 5167current unit, it must also have the No_Elaboration_Code_All aspect set. 5168It may be applied to package or subprogram specs or their generic versions. 5169 5170@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 5171@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a0} 5172@section Pragma No_Heap_Finalization 5173 5174 5175Syntax: 5176 5177@example 5178pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 5179@end example 5180 5181Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a 5182type-specific pragma. 5183 5184In its configuration form, the pragma must appear within a configuration file 5185such as gnat.adc, without an argument. The pragma suppresses the call to 5186@code{Finalize} for heap-allocated objects created through library-level named 5187access-to-object types in cases where the designated type requires finalization 5188actions. 5189 5190In its type-specific form, the argument of the pragma must denote a 5191library-level named access-to-object type. The pragma suppresses the call to 5192@code{Finalize} for heap-allocated objects created through the specific access type 5193in cases where the designated type requires finalization actions. 5194 5195It is still possible to finalize such heap-allocated objects by explicitly 5196deallocating them. 5197 5198A library-level named access-to-object type declared within a generic unit will 5199lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not 5200appear at the library level. 5201 5202@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas 5203@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a2} 5204@section Pragma No_Inline 5205 5206 5207Syntax: 5208 5209@example 5210pragma No_Inline (NAME @{, NAME@}); 5211@end example 5212 5213This pragma suppresses inlining for the callable entity or the instances of 5214the generic subprogram designated by @code{NAME}, including inlining that 5215results from the use of pragma @code{Inline}. This pragma is always active, 5216in particular it is not subject to the use of option @emph{-gnatn} or 5217@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 5218pragma @code{Inline_Always} for the same @code{NAME}. 5219 5220@node Pragma No_Return,Pragma No_Run_Time,Pragma No_Inline,Implementation Defined Pragmas 5221@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a3} 5222@section Pragma No_Return 5223 5224 5225Syntax: 5226 5227@example 5228pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5229@end example 5230 5231Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure 5232declarations in the current declarative part. A procedure to which this 5233pragma is applied may not contain any explicit @code{return} statements. 5234In addition, if the procedure contains any implicit returns from falling 5235off the end of a statement sequence, then execution of that implicit 5236return will cause Program_Error to be raised. 5237 5238One use of this pragma is to identify procedures whose only purpose is to raise 5239an exception. Another use of this pragma is to suppress incorrect warnings 5240about missing returns in functions, where the last statement of a function 5241statement sequence is a call to such a procedure. 5242 5243Note that in Ada 2005 mode, this pragma is part of the language. It is 5244available in all earlier versions of Ada as an implementation-defined 5245pragma. 5246 5247@node Pragma No_Run_Time,Pragma No_Strict_Aliasing,Pragma No_Return,Implementation Defined Pragmas 5248@anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{a4} 5249@section Pragma No_Run_Time 5250 5251 5252Syntax: 5253 5254@example 5255pragma No_Run_Time; 5256@end example 5257 5258This is an obsolete configuration pragma that historically was used to 5259set up a runtime library with no object code. It is now used only for 5260internal testing. The pragma has been superseded by the reconfigurable 5261runtime capability of GNAT. 5262 5263@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Run_Time,Implementation Defined Pragmas 5264@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a5} 5265@section Pragma No_Strict_Aliasing 5266 5267 5268Syntax: 5269 5270@example 5271pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5272@end example 5273 5274@code{type_LOCAL_NAME} must refer to an access type 5275declaration in the current declarative part. The effect is to inhibit 5276strict aliasing optimization for the given type. The form with no 5277arguments is a configuration pragma which applies to all access types 5278declared in units to which the pragma applies. For a detailed 5279description of the strict aliasing optimization, and the situations 5280in which it must be suppressed, see the section on Optimization and Strict Aliasing 5281in the @cite{GNAT User's Guide}. 5282 5283This pragma currently has no effects on access to unconstrained array types. 5284 5285@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5286@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a6}@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a7} 5287@section Pragma No_Tagged_Streams 5288 5289 5290Syntax: 5291 5292@example 5293pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5294@end example 5295 5296Normally when a tagged type is introduced using a full type declaration, 5297part of the processing includes generating stream access routines to be 5298used by stream attributes referencing the type (or one of its subtypes 5299or derived types). This can involve the generation of significant amounts 5300of code which is wasted space if stream routines are not needed for the 5301type in question. 5302 5303The @code{No_Tagged_Streams} pragma causes the generation of these stream 5304routines to be skipped, and any attempt to use stream operations on 5305types subject to this pragma will be statically rejected as illegal. 5306 5307There are two forms of the pragma. The form with no arguments must appear 5308in a declarative sequence or in the declarations of a package spec. This 5309pragma affects all subsequent root tagged types declared in the declaration 5310sequence, and specifies that no stream routines be generated. The form with 5311an argument (for which there is also a corresponding aspect) specifies a 5312single root tagged type for which stream routines are not to be generated. 5313 5314Once the pragma has been given for a particular root tagged type, all subtypes 5315and derived types of this type inherit the pragma automatically, so the effect 5316applies to a complete hierarchy (this is necessary to deal with the class-wide 5317dispatching versions of the stream routines). 5318 5319@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5320@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{a8} 5321@section Pragma Normalize_Scalars 5322 5323 5324Syntax: 5325 5326@example 5327pragma Normalize_Scalars; 5328@end example 5329 5330This is a language defined pragma which is fully implemented in GNAT. The 5331effect is to cause all scalar objects that are not otherwise initialized 5332to be initialized. The initial values are implementation dependent and 5333are as follows: 5334 5335 5336@table @asis 5337 5338@item @emph{Standard.Character} 5339 5340Objects whose root type is Standard.Character are initialized to 5341Character'Last unless the subtype range excludes NUL (in which case 5342NUL is used). This choice will always generate an invalid value if 5343one exists. 5344 5345@item @emph{Standard.Wide_Character} 5346 5347Objects whose root type is Standard.Wide_Character are initialized to 5348Wide_Character'Last unless the subtype range excludes NUL (in which case 5349NUL is used). This choice will always generate an invalid value if 5350one exists. 5351 5352@item @emph{Standard.Wide_Wide_Character} 5353 5354Objects whose root type is Standard.Wide_Wide_Character are initialized to 5355the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5356which case NUL is used). This choice will always generate an invalid value if 5357one exists. 5358 5359@item @emph{Integer types} 5360 5361Objects of an integer type are treated differently depending on whether 5362negative values are present in the subtype. If no negative values are 5363present, then all one bits is used as the initial value except in the 5364special case where zero is excluded from the subtype, in which case 5365all zero bits are used. This choice will always generate an invalid 5366value if one exists. 5367 5368For subtypes with negative values present, the largest negative number 5369is used, except in the unusual case where this largest negative number 5370is in the subtype, and the largest positive number is not, in which case 5371the largest positive value is used. This choice will always generate 5372an invalid value if one exists. 5373 5374@item @emph{Floating-Point Types} 5375 5376Objects of all floating-point types are initialized to all 1-bits. For 5377standard IEEE format, this corresponds to a NaN (not a number) which is 5378indeed an invalid value. 5379 5380@item @emph{Fixed-Point Types} 5381 5382Objects of all fixed-point types are treated as described above for integers, 5383with the rules applying to the underlying integer value used to represent 5384the fixed-point value. 5385 5386@item @emph{Modular types} 5387 5388Objects of a modular type are initialized to all one bits, except in 5389the special case where zero is excluded from the subtype, in which 5390case all zero bits are used. This choice will always generate an 5391invalid value if one exists. 5392 5393@item @emph{Enumeration types} 5394 5395Objects of an enumeration type are initialized to all one-bits, i.e., to 5396the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 5397whose Pos value is zero, in which case a code of zero is used. This choice 5398will always generate an invalid value if one exists. 5399@end table 5400 5401@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5402@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{aa} 5403@section Pragma Obsolescent 5404 5405 5406Syntax: 5407 5408@example 5409pragma Obsolescent; 5410 5411pragma Obsolescent ( 5412 [Message =>] static_string_EXPRESSION 5413[,[Version =>] Ada_05]]); 5414 5415pragma Obsolescent ( 5416 [Entity =>] NAME 5417[,[Message =>] static_string_EXPRESSION 5418[,[Version =>] Ada_05]] ); 5419@end example 5420 5421This pragma can occur immediately following a declaration of an entity, 5422including the case of a record component. If no Entity argument is present, 5423then this declaration is the one to which the pragma applies. If an Entity 5424parameter is present, it must either match the name of the entity in this 5425declaration, or alternatively, the pragma can immediately follow an enumeration 5426type declaration, where the Entity argument names one of the enumeration 5427literals. 5428 5429This pragma is used to indicate that the named entity 5430is considered obsolescent and should not be used. Typically this is 5431used when an API must be modified by eventually removing or modifying 5432existing subprograms or other entities. The pragma can be used at an 5433intermediate stage when the entity is still present, but will be 5434removed later. 5435 5436The effect of this pragma is to output a warning message on a reference to 5437an entity thus marked that the subprogram is obsolescent if the appropriate 5438warning option in the compiler is activated. If the @code{Message} parameter is 5439present, then a second warning message is given containing this text. In 5440addition, a reference to the entity is considered to be a violation of pragma 5441@code{Restrictions (No_Obsolescent_Features)}. 5442 5443This pragma can also be used as a program unit pragma for a package, 5444in which case the entity name is the name of the package, and the 5445pragma indicates that the entire package is considered 5446obsolescent. In this case a client @code{with}ing such a package 5447violates the restriction, and the @code{with} clause is 5448flagged with warnings if the warning option is set. 5449 5450If the @code{Version} parameter is present (which must be exactly 5451the identifier @code{Ada_05}, no other argument is allowed), then the 5452indication of obsolescence applies only when compiling in Ada 2005 5453mode. This is primarily intended for dealing with the situations 5454in the predefined library where subprograms or packages 5455have become defined as obsolescent in Ada 2005 5456(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. 5457 5458The following examples show typical uses of this pragma: 5459 5460@example 5461package p is 5462 pragma Obsolescent (p, Message => "use pp instead of p"); 5463end p; 5464 5465package q is 5466 procedure q2; 5467 pragma Obsolescent ("use q2new instead"); 5468 5469 type R is new integer; 5470 pragma Obsolescent 5471 (Entity => R, 5472 Message => "use RR in Ada 2005", 5473 Version => Ada_05); 5474 5475 type M is record 5476 F1 : Integer; 5477 F2 : Integer; 5478 pragma Obsolescent; 5479 F3 : Integer; 5480 end record; 5481 5482 type E is (a, bc, 'd', quack); 5483 pragma Obsolescent (Entity => bc) 5484 pragma Obsolescent (Entity => 'd') 5485 5486 function "+" 5487 (a, b : character) return character; 5488 pragma Obsolescent (Entity => "+"); 5489end; 5490@end example 5491 5492Note that, as for all pragmas, if you use a pragma argument identifier, 5493then all subsequent parameters must also use a pragma argument identifier. 5494So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} 5495argument is present, it must be preceded by @code{Message =>}. 5496 5497@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5498@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ab} 5499@section Pragma Optimize_Alignment 5500 5501 5502@geindex Alignment 5503@geindex default settings 5504 5505Syntax: 5506 5507@example 5508pragma Optimize_Alignment (TIME | SPACE | OFF); 5509@end example 5510 5511This is a configuration pragma which affects the choice of default alignments 5512for types and objects where no alignment is explicitly specified. There is a 5513time/space trade-off in the selection of these values. Large alignments result 5514in more efficient code, at the expense of larger data space, since sizes have 5515to be increased to match these alignments. Smaller alignments save space, but 5516the access code is slower. The normal choice of default alignments for types 5517and individual alignment promotions for objects (which is what you get if you 5518do not use this pragma, or if you use an argument of OFF), tries to balance 5519these two requirements. 5520 5521Specifying SPACE causes smaller default alignments to be chosen in two cases. 5522First any packed record is given an alignment of 1. Second, if a size is given 5523for the type, then the alignment is chosen to avoid increasing this size. For 5524example, consider: 5525 5526@example 5527type R is record 5528 X : Integer; 5529 Y : Character; 5530end record; 5531 5532for R'Size use 5*8; 5533@end example 5534 5535In the default mode, this type gets an alignment of 4, so that access to the 5536Integer field X are efficient. But this means that objects of the type end up 5537with a size of 8 bytes. This is a valid choice, since sizes of objects are 5538allowed to be bigger than the size of the type, but it can waste space if for 5539example fields of type R appear in an enclosing record. If the above type is 5540compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5541 5542However, there is one case in which SPACE is ignored. If a variable length 5543record (that is a discriminated record with a component which is an array 5544whose length depends on a discriminant), has a pragma Pack, then it is not 5545in general possible to set the alignment of such a record to one, so the 5546pragma is ignored in this case (with a warning). 5547 5548Specifying SPACE also disables alignment promotions for standalone objects, 5549which occur when the compiler increases the alignment of a specific object 5550without changing the alignment of its type. 5551 5552Specifying SPACE also disables component reordering in unpacked record types, 5553which can result in larger sizes in order to meet alignment requirements. 5554 5555Specifying TIME causes larger default alignments to be chosen in the case of 5556small types with sizes that are not a power of 2. For example, consider: 5557 5558@example 5559type R is record 5560 A : Character; 5561 B : Character; 5562 C : Boolean; 5563end record; 5564 5565pragma Pack (R); 5566for R'Size use 17; 5567@end example 5568 5569The default alignment for this record is normally 1, but if this type is 5570compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 5571to 4, which wastes space for objects of the type, since they are now 4 bytes 5572long, but results in more efficient access when the whole record is referenced. 5573 5574As noted above, this is a configuration pragma, and there is a requirement 5575that all units in a partition be compiled with a consistent setting of the 5576optimization setting. This would normally be achieved by use of a configuration 5577pragma file containing the appropriate setting. The exception to this rule is 5578that units with an explicit configuration pragma in the same file as the source 5579unit are excluded from the consistency check, as are all predefined units. The 5580latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5581pragma appears at the start of the file. 5582 5583@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5584@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{ac} 5585@section Pragma Ordered 5586 5587 5588Syntax: 5589 5590@example 5591pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5592@end example 5593 5594Most enumeration types are from a conceptual point of view unordered. 5595For example, consider: 5596 5597@example 5598type Color is (Red, Blue, Green, Yellow); 5599@end example 5600 5601By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 5602but really these relations make no sense; the enumeration type merely 5603specifies a set of possible colors, and the order is unimportant. 5604 5605For unordered enumeration types, it is generally a good idea if 5606clients avoid comparisons (other than equality or inequality) and 5607explicit ranges. (A @emph{client} is a unit where the type is referenced, 5608other than the unit where the type is declared, its body, and its subunits.) 5609For example, if code buried in some client says: 5610 5611@example 5612if Current_Color < Yellow then ... 5613if Current_Color in Blue .. Green then ... 5614@end example 5615 5616then the client code is relying on the order, which is undesirable. 5617It makes the code hard to read and creates maintenance difficulties if 5618entries have to be added to the enumeration type. Instead, 5619the code in the client should list the possibilities, or an 5620appropriate subtype should be declared in the unit that declares 5621the original enumeration type. E.g., the following subtype could 5622be declared along with the type @code{Color}: 5623 5624@example 5625subtype RBG is Color range Red .. Green; 5626@end example 5627 5628and then the client could write: 5629 5630@example 5631if Current_Color in RBG then ... 5632if Current_Color = Blue or Current_Color = Green then ... 5633@end example 5634 5635However, some enumeration types are legitimately ordered from a conceptual 5636point of view. For example, if you declare: 5637 5638@example 5639type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5640@end example 5641 5642then the ordering imposed by the language is reasonable, and 5643clients can depend on it, writing for example: 5644 5645@example 5646if D in Mon .. Fri then ... 5647if D < Wed then ... 5648@end example 5649 5650The pragma @emph{Ordered} is provided to mark enumeration types that 5651are conceptually ordered, alerting the reader that clients may depend 5652on the ordering. GNAT provides a pragma to mark enumerations as ordered 5653rather than one to mark them as unordered, since in our experience, 5654the great majority of enumeration types are conceptually unordered. 5655 5656The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 5657and @code{Wide_Wide_Character} 5658are considered to be ordered types, so each is declared with a 5659pragma @code{Ordered} in package @code{Standard}. 5660 5661Normally pragma @code{Ordered} serves only as documentation and a guide for 5662coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 5663requests warnings for inappropriate uses (comparisons and explicit 5664subranges) for unordered types. If this switch is used, then any 5665enumeration type not marked with pragma @code{Ordered} will be considered 5666as unordered, and will generate warnings for inappropriate uses. 5667 5668Note that generic types are not considered ordered or unordered (since the 5669template can be instantiated for both cases), so we never generate warnings 5670for the case of generic enumerated types. 5671 5672For additional information please refer to the description of the 5673@emph{-gnatw.u} switch in the GNAT User's Guide. 5674 5675@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 5676@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{ad} 5677@section Pragma Overflow_Mode 5678 5679 5680Syntax: 5681 5682@example 5683pragma Overflow_Mode 5684 ( [General =>] MODE 5685 [,[Assertions =>] MODE]); 5686 5687MODE ::= STRICT | MINIMIZED | ELIMINATED 5688@end example 5689 5690This pragma sets the current overflow mode to the given setting. For details 5691of the meaning of these modes, please refer to the 5692'Overflow Check Handling in GNAT' appendix in the 5693GNAT User's Guide. If only the @code{General} parameter is present, 5694the given mode applies to all expressions. If both parameters are present, 5695the @code{General} mode applies to expressions outside assertions, and 5696the @code{Eliminated} mode applies to expressions within assertions. 5697 5698The case of the @code{MODE} parameter is ignored, 5699so @code{MINIMIZED}, @code{Minimized} and 5700@code{minimized} all have the same effect. 5701 5702The @code{Overflow_Mode} pragma has the same scoping and placement 5703rules as pragma @code{Suppress}, so it can occur either as a 5704configuration pragma, specifying a default for the whole 5705program, or in a declarative scope, where it applies to the 5706remaining declarations and statements in that scope. 5707 5708The pragma @code{Suppress (Overflow_Check)} suppresses 5709overflow checking, but does not affect the overflow mode. 5710 5711The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 5712overflow checking, but does not affect the overflow mode. 5713 5714@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 5715@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{ae} 5716@section Pragma Overriding_Renamings 5717 5718 5719@geindex Rational profile 5720 5721@geindex Rational compatibility 5722 5723Syntax: 5724 5725@example 5726pragma Overriding_Renamings; 5727@end example 5728 5729This is a GNAT configuration pragma to simplify porting 5730legacy code accepted by the Rational 5731Ada compiler. In the presence of this pragma, a renaming declaration that 5732renames an inherited operation declared in the same scope is legal if selected 5733notation is used as in: 5734 5735@example 5736pragma Overriding_Renamings; 5737... 5738package R is 5739 function F (..); 5740 ... 5741 function F (..) renames R.F; 5742end R; 5743@end example 5744 5745even though 5746RM 8.3 (15) stipulates that an overridden operation is not visible within the 5747declaration of the overriding operation. 5748 5749@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 5750@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{af} 5751@section Pragma Partition_Elaboration_Policy 5752 5753 5754Syntax: 5755 5756@example 5757pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 5758 5759POLICY_IDENTIFIER ::= Concurrent | Sequential 5760@end example 5761 5762This pragma is standard in Ada 2005, but is available in all earlier 5763versions of Ada as an implementation-defined pragma. 5764See Ada 2012 Reference Manual for details. 5765 5766@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 5767@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{b0}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b1} 5768@section Pragma Part_Of 5769 5770 5771Syntax: 5772 5773@example 5774pragma Part_Of (ABSTRACT_STATE); 5775 5776ABSTRACT_STATE ::= NAME 5777@end example 5778 5779For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the 5780SPARK 2014 Reference Manual, section 7.2.6. 5781 5782@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 5783@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b2} 5784@section Pragma Passive 5785 5786 5787Syntax: 5788 5789@example 5790pragma Passive [(Semaphore | No)]; 5791@end example 5792 5793Syntax checked, but otherwise ignored by GNAT. This is recognized for 5794compatibility with DEC Ada 83 implementations, where it is used within a 5795task definition to request that a task be made passive. If the argument 5796@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 5797treats the pragma as an assertion that the containing task is passive 5798and that optimization of context switch with this task is permitted and 5799desired. If the argument @code{No} is present, the task must not be 5800optimized. GNAT does not attempt to optimize any tasks in this manner 5801(since protected objects are available in place of passive tasks). 5802 5803For more information on the subject of passive tasks, see the section 5804'Passive Task Optimization' in the GNAT Users Guide. 5805 5806@node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas 5807@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b4} 5808@section Pragma Persistent_BSS 5809 5810 5811Syntax: 5812 5813@example 5814pragma Persistent_BSS [(LOCAL_NAME)] 5815@end example 5816 5817This pragma allows selected objects to be placed in the @code{.persistent_bss} 5818section. On some targets the linker and loader provide for special 5819treatment of this section, allowing a program to be reloaded without 5820affecting the contents of this data (hence the name persistent). 5821 5822There are two forms of usage. If an argument is given, it must be the 5823local name of a library-level object, with no explicit initialization 5824and whose type is potentially persistent. If no argument is given, then 5825the pragma is a configuration pragma, and applies to all library-level 5826objects with no explicit initialization of potentially persistent types. 5827 5828A potentially persistent type is a scalar type, or an untagged, 5829non-discriminated record, all of whose components have no explicit 5830initialization and are themselves of a potentially persistent type, 5831or an array, all of whose constraints are static, and whose component 5832type is potentially persistent. 5833 5834If this pragma is used on a target where this feature is not supported, 5835then the pragma will be ignored. See also @code{pragma Linker_Section}. 5836 5837@node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas 5838@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{b5} 5839@section Pragma Polling 5840 5841 5842Syntax: 5843 5844@example 5845pragma Polling (ON | OFF); 5846@end example 5847 5848This pragma controls the generation of polling code. This is normally off. 5849If @code{pragma Polling (ON)} is used then periodic calls are generated to 5850the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 5851runtime library, and can be found in file @code{a-excpol.adb}. 5852 5853Pragma @code{Polling} can appear as a configuration pragma (for example it 5854can be placed in the @code{gnat.adc} file) to enable polling globally, or it 5855can be used in the statement or declaration sequence to control polling 5856more locally. 5857 5858A call to the polling routine is generated at the start of every loop and 5859at the start of every subprogram call. This guarantees that the @code{Poll} 5860routine is called frequently, and places an upper bound (determined by 5861the complexity of the code) on the period between two @code{Poll} calls. 5862 5863The primary purpose of the polling interface is to enable asynchronous 5864aborts on targets that cannot otherwise support it (for example Windows 5865NT), but it may be used for any other purpose requiring periodic polling. 5866The standard version is null, and can be replaced by a user program. This 5867will require re-compilation of the @code{Ada.Exceptions} package that can 5868be found in files @code{a-except.ads} and @code{a-except.adb}. 5869 5870A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT 5871distribution) is used to enable the asynchronous abort capability on 5872targets that do not normally support the capability. The version of 5873@code{Poll} in this file makes a call to the appropriate runtime routine 5874to test for an abort condition. 5875 5876Note that polling can also be enabled by use of the @emph{-gnatP} switch. 5877See the section on switches for gcc in the @cite{GNAT User's Guide}. 5878 5879@node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas 5880@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b6} 5881@section Pragma Post 5882 5883 5884@geindex Post 5885 5886@geindex Checks 5887@geindex postconditions 5888 5889Syntax: 5890 5891@example 5892pragma Post (Boolean_Expression); 5893@end example 5894 5895The @code{Post} pragma is intended to be an exact replacement for 5896the language-defined 5897@code{Post} aspect, and shares its restrictions and semantics. 5898It must appear either immediately following the corresponding 5899subprogram declaration (only other pragmas may intervene), or 5900if there is no separate subprogram declaration, then it can 5901appear at the start of the declarations in a subprogram body 5902(preceded only by other pragmas). 5903 5904@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 5905@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b7} 5906@section Pragma Postcondition 5907 5908 5909@geindex Postcondition 5910 5911@geindex Checks 5912@geindex postconditions 5913 5914Syntax: 5915 5916@example 5917pragma Postcondition ( 5918 [Check =>] Boolean_Expression 5919 [,[Message =>] String_Expression]); 5920@end example 5921 5922The @code{Postcondition} pragma allows specification of automatic 5923postcondition checks for subprograms. These checks are similar to 5924assertions, but are automatically inserted just prior to the return 5925statements of the subprogram with which they are associated (including 5926implicit returns at the end of procedure bodies and associated 5927exception handlers). 5928 5929In addition, the boolean expression which is the condition which 5930must be true may contain references to function'Result in the case 5931of a function to refer to the returned value. 5932 5933@code{Postcondition} pragmas may appear either immediately following the 5934(separate) declaration of a subprogram, or at the start of the 5935declarations of a subprogram body. Only other pragmas may intervene 5936(that is appear between the subprogram declaration and its 5937postconditions, or appear before the postcondition in the 5938declaration sequence in a subprogram body). In the case of a 5939postcondition appearing after a subprogram declaration, the 5940formal arguments of the subprogram are visible, and can be 5941referenced in the postcondition expressions. 5942 5943The postconditions are collected and automatically tested just 5944before any return (implicit or explicit) in the subprogram body. 5945A postcondition is only recognized if postconditions are active 5946at the time the pragma is encountered. The compiler switch @emph{gnata} 5947turns on all postconditions by default, and pragma @code{Check_Policy} 5948with an identifier of @code{Postcondition} can also be used to 5949control whether postconditions are active. 5950 5951The general approach is that postconditions are placed in the spec 5952if they represent functional aspects which make sense to the client. 5953For example we might have: 5954 5955@example 5956function Direction return Integer; 5957pragma Postcondition 5958 (Direction'Result = +1 5959 or else 5960 Direction'Result = -1); 5961@end example 5962 5963which serves to document that the result must be +1 or -1, and 5964will test that this is the case at run time if postcondition 5965checking is active. 5966 5967Postconditions within the subprogram body can be used to 5968check that some internal aspect of the implementation, 5969not visible to the client, is operating as expected. 5970For instance if a square root routine keeps an internal 5971counter of the number of times it is called, then we 5972might have the following postcondition: 5973 5974@example 5975Sqrt_Calls : Natural := 0; 5976 5977function Sqrt (Arg : Float) return Float is 5978 pragma Postcondition 5979 (Sqrt_Calls = Sqrt_Calls'Old + 1); 5980 ... 5981end Sqrt 5982@end example 5983 5984As this example, shows, the use of the @code{Old} attribute 5985is often useful in postconditions to refer to the state on 5986entry to the subprogram. 5987 5988Note that postconditions are only checked on normal returns 5989from the subprogram. If an abnormal return results from 5990raising an exception, then the postconditions are not checked. 5991 5992If a postcondition fails, then the exception 5993@code{System.Assertions.Assert_Failure} is raised. If 5994a message argument was supplied, then the given string 5995will be used as the exception message. If no message 5996argument was supplied, then the default message has 5997the form "Postcondition failed at file_name:line". The 5998exception is raised in the context of the subprogram 5999body, so it is possible to catch postcondition failures 6000within the subprogram body itself. 6001 6002Within a package spec, normal visibility rules 6003in Ada would prevent forward references within a 6004postcondition pragma to functions defined later in 6005the same package. This would introduce undesirable 6006ordering constraints. To avoid this problem, all 6007postcondition pragmas are analyzed at the end of 6008the package spec, allowing forward references. 6009 6010The following example shows that this even allows 6011mutually recursive postconditions as in: 6012 6013@example 6014package Parity_Functions is 6015 function Odd (X : Natural) return Boolean; 6016 pragma Postcondition 6017 (Odd'Result = 6018 (x = 1 6019 or else 6020 (x /= 0 and then Even (X - 1)))); 6021 6022 function Even (X : Natural) return Boolean; 6023 pragma Postcondition 6024 (Even'Result = 6025 (x = 0 6026 or else 6027 (x /= 1 and then Odd (X - 1)))); 6028 6029end Parity_Functions; 6030@end example 6031 6032There are no restrictions on the complexity or form of 6033conditions used within @code{Postcondition} pragmas. 6034The following example shows that it is even possible 6035to verify performance behavior. 6036 6037@example 6038package Sort is 6039 6040 Performance : constant Float; 6041 -- Performance constant set by implementation 6042 -- to match target architecture behavior. 6043 6044 procedure Treesort (Arg : String); 6045 -- Sorts characters of argument using N*logN sort 6046 pragma Postcondition 6047 (Float (Clock - Clock'Old) <= 6048 Float (Arg'Length) * 6049 log (Float (Arg'Length)) * 6050 Performance); 6051end Sort; 6052@end example 6053 6054Note: postcondition pragmas associated with subprograms that are 6055marked as Inline_Always, or those marked as Inline with front-end 6056inlining (-gnatN option set) are accepted and legality-checked 6057by the compiler, but are ignored at run-time even if postcondition 6058checking is enabled. 6059 6060Note that pragma @code{Postcondition} differs from the language-defined 6061@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 6062multiple occurrences, allowing occurences in the body even if there 6063is a separate spec, and allowing a second string parameter, and the 6064use of the pragma identifier @code{Check}. Historically, pragma 6065@code{Postcondition} was implemented prior to the development of 6066Ada 2012, and has been retained in its original form for 6067compatibility purposes. 6068 6069@node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas 6070@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b8} 6071@section Pragma Post_Class 6072 6073 6074@geindex Post 6075 6076@geindex Checks 6077@geindex postconditions 6078 6079Syntax: 6080 6081@example 6082pragma Post_Class (Boolean_Expression); 6083@end example 6084 6085The @code{Post_Class} pragma is intended to be an exact replacement for 6086the language-defined 6087@code{Post'Class} aspect, and shares its restrictions and semantics. 6088It must appear either immediately following the corresponding 6089subprogram declaration (only other pragmas may intervene), or 6090if there is no separate subprogram declaration, then it can 6091appear at the start of the declarations in a subprogram body 6092(preceded only by other pragmas). 6093 6094Note: This pragma is called @code{Post_Class} rather than 6095@code{Post'Class} because the latter would not be strictly 6096conforming to the allowed syntax for pragmas. The motivation 6097for provinding pragmas equivalent to the aspects is to allow a program 6098to be written using the pragmas, and then compiled if necessary 6099using an Ada compiler that does not recognize the pragmas or 6100aspects, but is prepared to ignore the pragmas. The assertion 6101policy that controls this pragma is @code{Post'Class}, not 6102@code{Post_Class}. 6103 6104@node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas 6105@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{b9} 6106@section Pragma Rename_Pragma 6107 6108 6109@geindex Pragmas 6110@geindex synonyms 6111 6112Syntax: 6113 6114@example 6115pragma Rename_Pragma ( 6116 [New_Name =>] IDENTIFIER, 6117 [Renamed =>] pragma_IDENTIFIER); 6118@end example 6119 6120This pragma provides a mechanism for supplying new names for existing 6121pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for 6122the Renamed pragma. For example, suppose you have code that was originally 6123developed on a compiler that supports Inline_Only as an implementation defined 6124pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 6125least very similar to) the GNAT implementation defined pragma 6126Inline_Always. You could globally replace Inline_Only with Inline_Always. 6127 6128However, to avoid that source modification, you could instead add a 6129configuration pragma: 6130 6131@example 6132pragma Rename_Pragma ( 6133 New_Name => Inline_Only, 6134 Renamed => Inline_Always); 6135@end example 6136 6137Then GNAT will treat "pragma Inline_Only ..." as if you had written 6138"pragma Inline_Always ...". 6139 6140Pragma Inline_Only will not necessarily mean the same thing as the other Ada 6141compiler; it's up to you to make sure the semantics are close enough. 6142 6143@node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas 6144@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba} 6145@section Pragma Pre 6146 6147 6148@geindex Pre 6149 6150@geindex Checks 6151@geindex preconditions 6152 6153Syntax: 6154 6155@example 6156pragma Pre (Boolean_Expression); 6157@end example 6158 6159The @code{Pre} pragma is intended to be an exact replacement for 6160the language-defined 6161@code{Pre} aspect, and shares its restrictions and semantics. 6162It must appear either immediately following the corresponding 6163subprogram declaration (only other pragmas may intervene), or 6164if there is no separate subprogram declaration, then it can 6165appear at the start of the declarations in a subprogram body 6166(preceded only by other pragmas). 6167 6168@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 6169@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb} 6170@section Pragma Precondition 6171 6172 6173@geindex Preconditions 6174 6175@geindex Checks 6176@geindex preconditions 6177 6178Syntax: 6179 6180@example 6181pragma Precondition ( 6182 [Check =>] Boolean_Expression 6183 [,[Message =>] String_Expression]); 6184@end example 6185 6186The @code{Precondition} pragma is similar to @code{Postcondition} 6187except that the corresponding checks take place immediately upon 6188entry to the subprogram, and if a precondition fails, the exception 6189is raised in the context of the caller, and the attribute 'Result 6190cannot be used within the precondition expression. 6191 6192Otherwise, the placement and visibility rules are identical to those 6193described for postconditions. The following is an example of use 6194within a package spec: 6195 6196@example 6197package Math_Functions is 6198 ... 6199 function Sqrt (Arg : Float) return Float; 6200 pragma Precondition (Arg >= 0.0) 6201 ... 6202end Math_Functions; 6203@end example 6204 6205@code{Precondition} pragmas may appear either immediately following the 6206(separate) declaration of a subprogram, or at the start of the 6207declarations of a subprogram body. Only other pragmas may intervene 6208(that is appear between the subprogram declaration and its 6209postconditions, or appear before the postcondition in the 6210declaration sequence in a subprogram body). 6211 6212Note: precondition pragmas associated with subprograms that are 6213marked as Inline_Always, or those marked as Inline with front-end 6214inlining (-gnatN option set) are accepted and legality-checked 6215by the compiler, but are ignored at run-time even if precondition 6216checking is enabled. 6217 6218Note that pragma @code{Precondition} differs from the language-defined 6219@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 6220multiple occurrences, allowing occurences in the body even if there 6221is a separate spec, and allowing a second string parameter, and the 6222use of the pragma identifier @code{Check}. Historically, pragma 6223@code{Precondition} was implemented prior to the development of 6224Ada 2012, and has been retained in its original form for 6225compatibility purposes. 6226 6227@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 6228@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd} 6229@section Pragma Predicate 6230 6231 6232Syntax: 6233 6234@example 6235pragma Predicate 6236 ([Entity =>] type_LOCAL_NAME, 6237 [Check =>] EXPRESSION); 6238@end example 6239 6240This pragma (available in all versions of Ada in GNAT) encompasses both 6241the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 6242Ada 2012. A predicate is regarded as static if it has an allowed form 6243for @code{Static_Predicate} and is otherwise treated as a 6244@code{Dynamic_Predicate}. Otherwise, predicates specified by this 6245pragma behave exactly as described in the Ada 2012 reference manual. 6246For example, if we have 6247 6248@example 6249type R is range 1 .. 10; 6250subtype S is R; 6251pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6252subtype Q is R 6253pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6254@end example 6255 6256the effect is identical to the following Ada 2012 code: 6257 6258@example 6259type R is range 1 .. 10; 6260subtype S is R with 6261 Static_Predicate => S not in 4 .. 6; 6262subtype Q is R with 6263 Dynamic_Predicate => F(Q) or G(Q); 6264@end example 6265 6266Note that there are no pragmas @code{Dynamic_Predicate} 6267or @code{Static_Predicate}. That is 6268because these pragmas would affect legality and semantics of 6269the program and thus do not have a neutral effect if ignored. 6270The motivation behind providing pragmas equivalent to 6271corresponding aspects is to allow a program to be written 6272using the pragmas, and then compiled with a compiler that 6273will ignore the pragmas. That doesn't work in the case of 6274static and dynamic predicates, since if the corresponding 6275pragmas are ignored, then the behavior of the program is 6276fundamentally changed (for example a membership test 6277@code{A in B} would not take into account a predicate 6278defined for subtype B). When following this approach, the 6279use of predicates should be avoided. 6280 6281@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6282@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{be} 6283@section Pragma Predicate_Failure 6284 6285 6286Syntax: 6287 6288@example 6289pragma Predicate_Failure 6290 ([Entity =>] type_LOCAL_NAME, 6291 [Message =>] String_Expression); 6292@end example 6293 6294The @code{Predicate_Failure} pragma is intended to be an exact replacement for 6295the language-defined 6296@code{Predicate_Failure} aspect, and shares its restrictions and semantics. 6297 6298@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6299@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bf} 6300@section Pragma Preelaborable_Initialization 6301 6302 6303Syntax: 6304 6305@example 6306pragma Preelaborable_Initialization (DIRECT_NAME); 6307@end example 6308 6309This pragma is standard in Ada 2005, but is available in all earlier 6310versions of Ada as an implementation-defined pragma. 6311See Ada 2012 Reference Manual for details. 6312 6313@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6314@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c0} 6315@section Pragma Prefix_Exception_Messages 6316 6317 6318@geindex Prefix_Exception_Messages 6319 6320@geindex exception 6321 6322@geindex Exception_Message 6323 6324Syntax: 6325 6326@example 6327pragma Prefix_Exception_Messages; 6328@end example 6329 6330This is an implementation-defined configuration pragma that affects the 6331behavior of raise statements with a message given as a static string 6332constant (typically a string literal). In such cases, the string will 6333be automatically prefixed by the name of the enclosing entity (giving 6334the package and subprogram containing the raise statement). This helps 6335to identify where messages are coming from, and this mode is automatic 6336for the run-time library. 6337 6338The pragma has no effect if the message is computed with an expression other 6339than a static string constant, since the assumption in this case is that 6340the program computes exactly the string it wants. If you still want the 6341prefixing in this case, you can always call 6342@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6343 6344@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6345@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c1} 6346@section Pragma Pre_Class 6347 6348 6349@geindex Pre_Class 6350 6351@geindex Checks 6352@geindex preconditions 6353 6354Syntax: 6355 6356@example 6357pragma Pre_Class (Boolean_Expression); 6358@end example 6359 6360The @code{Pre_Class} pragma is intended to be an exact replacement for 6361the language-defined 6362@code{Pre'Class} aspect, and shares its restrictions and semantics. 6363It must appear either immediately following the corresponding 6364subprogram declaration (only other pragmas may intervene), or 6365if there is no separate subprogram declaration, then it can 6366appear at the start of the declarations in a subprogram body 6367(preceded only by other pragmas). 6368 6369Note: This pragma is called @code{Pre_Class} rather than 6370@code{Pre'Class} because the latter would not be strictly 6371conforming to the allowed syntax for pragmas. The motivation 6372for providing pragmas equivalent to the aspects is to allow a program 6373to be written using the pragmas, and then compiled if necessary 6374using an Ada compiler that does not recognize the pragmas or 6375aspects, but is prepared to ignore the pragmas. The assertion 6376policy that controls this pragma is @code{Pre'Class}, not 6377@code{Pre_Class}. 6378 6379@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6380@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c2} 6381@section Pragma Priority_Specific_Dispatching 6382 6383 6384Syntax: 6385 6386@example 6387pragma Priority_Specific_Dispatching ( 6388 POLICY_IDENTIFIER, 6389 first_priority_EXPRESSION, 6390 last_priority_EXPRESSION) 6391 6392POLICY_IDENTIFIER ::= 6393 EDF_Across_Priorities | 6394 FIFO_Within_Priorities | 6395 Non_Preemptive_Within_Priorities | 6396 Round_Robin_Within_Priorities 6397@end example 6398 6399This pragma is standard in Ada 2005, but is available in all earlier 6400versions of Ada as an implementation-defined pragma. 6401See Ada 2012 Reference Manual for details. 6402 6403@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6404@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c3} 6405@section Pragma Profile 6406 6407 6408Syntax: 6409 6410@example 6411pragma Profile (Ravenscar | Restricted | Rational | 6412 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 6413@end example 6414 6415This pragma is standard in Ada 2005, but is available in all earlier 6416versions of Ada as an implementation-defined pragma. This is a 6417configuration pragma that establishes a set of configuration pragmas 6418that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 6419The other possibilities (@code{Restricted}, @code{Rational}, 6420@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) 6421are implementation-defined. The set of configuration pragmas 6422is defined in the following sections. 6423 6424 6425@itemize * 6426 6427@item 6428Pragma Profile (Ravenscar) 6429 6430The @code{Ravenscar} profile is standard in Ada 2005, 6431but is available in all earlier 6432versions of Ada as an implementation-defined pragma. This profile 6433establishes the following set of configuration pragmas: 6434 6435 6436@itemize * 6437 6438@item 6439@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6440 6441[RM D.2.2] Tasks are dispatched following a preemptive 6442priority-ordered scheduling policy. 6443 6444@item 6445@code{Locking_Policy (Ceiling_Locking)} 6446 6447[RM D.3] While tasks and interrupts execute a protected action, they inherit 6448the ceiling priority of the corresponding protected object. 6449 6450@item 6451@code{Detect_Blocking} 6452 6453This pragma forces the detection of potentially blocking operations within a 6454protected operation, and to raise Program_Error if that happens. 6455@end itemize 6456 6457plus the following set of restrictions: 6458 6459 6460@itemize * 6461 6462@item 6463@code{Max_Entry_Queue_Length => 1} 6464 6465No task can be queued on a protected entry. 6466 6467@item 6468@code{Max_Protected_Entries => 1} 6469 6470@item 6471@code{Max_Task_Entries => 0} 6472 6473No rendezvous statements are allowed. 6474 6475@item 6476@code{No_Abort_Statements} 6477 6478@item 6479@code{No_Dynamic_Attachment} 6480 6481@item 6482@code{No_Dynamic_Priorities} 6483 6484@item 6485@code{No_Implicit_Heap_Allocations} 6486 6487@item 6488@code{No_Local_Protected_Objects} 6489 6490@item 6491@code{No_Local_Timing_Events} 6492 6493@item 6494@code{No_Protected_Type_Allocators} 6495 6496@item 6497@code{No_Relative_Delay} 6498 6499@item 6500@code{No_Requeue_Statements} 6501 6502@item 6503@code{No_Select_Statements} 6504 6505@item 6506@code{No_Specific_Termination_Handlers} 6507 6508@item 6509@code{No_Task_Allocators} 6510 6511@item 6512@code{No_Task_Hierarchy} 6513 6514@item 6515@code{No_Task_Termination} 6516 6517@item 6518@code{Simple_Barriers} 6519@end itemize 6520 6521The Ravenscar profile also includes the following restrictions that specify 6522that there are no semantic dependences on the corresponding predefined 6523packages: 6524 6525 6526@itemize * 6527 6528@item 6529@code{No_Dependence => Ada.Asynchronous_Task_Control} 6530 6531@item 6532@code{No_Dependence => Ada.Calendar} 6533 6534@item 6535@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6536 6537@item 6538@code{No_Dependence => Ada.Execution_Time.Timers} 6539 6540@item 6541@code{No_Dependence => Ada.Task_Attributes} 6542 6543@item 6544@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6545@end itemize 6546 6547This set of configuration pragmas and restrictions correspond to the 6548definition of the 'Ravenscar Profile' for limited tasking, devised and 6549published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6550A description is also available at 6551@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6552 6553The original definition of the profile was revised at subsequent IRTAW 6554meetings. It has been included in the ISO 6555@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6556and was made part of the Ada 2005 standard. 6557The formal definition given by 6558the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6559AI-305) available at 6560@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6561@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6562 6563The above set is a superset of the restrictions provided by pragma 6564@code{Profile (Restricted)}, it includes six additional restrictions 6565(@code{Simple_Barriers}, @code{No_Select_Statements}, 6566@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6567@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6568that pragma @code{Profile (Ravenscar)}, like the pragma 6569@code{Profile (Restricted)}, 6570automatically causes the use of a simplified, 6571more efficient version of the tasking run-time library. 6572 6573@item 6574Pragma Profile (GNAT_Extended_Ravenscar) 6575 6576This profile corresponds to a GNAT specific extension of the 6577Ravenscar profile. The profile may change in the future although 6578only in a compatible way: some restrictions may be removed or 6579relaxed. It is defined as a variation of the Ravenscar profile. 6580 6581The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6582by @code{No_Implicit_Task_Allocations} and 6583@code{No_Implicit_Protected_Object_Allocations}. 6584 6585The @code{Simple_Barriers} restriction has been replaced by 6586@code{Pure_Barriers}. 6587 6588The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and 6589@code{No_Relative_Delay} restrictions have been removed. 6590 6591@item 6592Pragma Profile (GNAT_Ravenscar_EDF) 6593 6594This profile corresponds to the Ravenscar profile but using 6595EDF_Across_Priority as the Task_Scheduling_Policy. 6596 6597@item 6598Pragma Profile (Restricted) 6599 6600This profile corresponds to the GNAT restricted run time. It 6601establishes the following set of restrictions: 6602 6603 6604@itemize * 6605 6606@item 6607@code{No_Abort_Statements} 6608 6609@item 6610@code{No_Entry_Queue} 6611 6612@item 6613@code{No_Task_Hierarchy} 6614 6615@item 6616@code{No_Task_Allocators} 6617 6618@item 6619@code{No_Dynamic_Priorities} 6620 6621@item 6622@code{No_Terminate_Alternatives} 6623 6624@item 6625@code{No_Dynamic_Attachment} 6626 6627@item 6628@code{No_Protected_Type_Allocators} 6629 6630@item 6631@code{No_Local_Protected_Objects} 6632 6633@item 6634@code{No_Requeue_Statements} 6635 6636@item 6637@code{No_Task_Attributes_Package} 6638 6639@item 6640@code{Max_Asynchronous_Select_Nesting = 0} 6641 6642@item 6643@code{Max_Task_Entries = 0} 6644 6645@item 6646@code{Max_Protected_Entries = 1} 6647 6648@item 6649@code{Max_Select_Alternatives = 0} 6650@end itemize 6651 6652This set of restrictions causes the automatic selection of a simplified 6653version of the run time that provides improved performance for the 6654limited set of tasking functionality permitted by this set of restrictions. 6655 6656@item 6657Pragma Profile (Rational) 6658 6659The Rational profile is intended to facilitate porting legacy code that 6660compiles with the Rational APEX compiler, even when the code includes non- 6661conforming Ada constructs. The profile enables the following three pragmas: 6662 6663 6664@itemize * 6665 6666@item 6667@code{pragma Implicit_Packing} 6668 6669@item 6670@code{pragma Overriding_Renamings} 6671 6672@item 6673@code{pragma Use_VADS_Size} 6674@end itemize 6675@end itemize 6676 6677@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6678@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4} 6679@section Pragma Profile_Warnings 6680 6681 6682Syntax: 6683 6684@example 6685pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6686@end example 6687 6688This is an implementation-defined pragma that is similar in 6689effect to @code{pragma Profile} except that instead of 6690generating @code{Restrictions} pragmas, it generates 6691@code{Restriction_Warnings} pragmas. The result is that 6692violations of the profile generate warning messages instead 6693of error messages. 6694 6695@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 6696@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c5} 6697@section Pragma Propagate_Exceptions 6698 6699 6700@geindex Interfacing to C++ 6701 6702Syntax: 6703 6704@example 6705pragma Propagate_Exceptions; 6706@end example 6707 6708This pragma is now obsolete and, other than generating a warning if warnings 6709on obsolescent features are enabled, is ignored. 6710It is retained for compatibility 6711purposes. It used to be used in connection with optimization of 6712a now-obsolete mechanism for implementation of exceptions. 6713 6714@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 6715@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c6} 6716@section Pragma Provide_Shift_Operators 6717 6718 6719@geindex Shift operators 6720 6721Syntax: 6722 6723@example 6724pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 6725@end example 6726 6727This pragma can be applied to a first subtype local name that specifies 6728either an unsigned or signed type. It has the effect of providing the 6729five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 6730Rotate_Left and Rotate_Right) for the given type. It is similar to 6731including the function declarations for these five operators, together 6732with the pragma Import (Intrinsic, ...) statements. 6733 6734@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 6735@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c7} 6736@section Pragma Psect_Object 6737 6738 6739Syntax: 6740 6741@example 6742pragma Psect_Object ( 6743 [Internal =>] LOCAL_NAME, 6744 [, [External =>] EXTERNAL_SYMBOL] 6745 [, [Size =>] EXTERNAL_SYMBOL]); 6746 6747EXTERNAL_SYMBOL ::= 6748 IDENTIFIER 6749| static_string_EXPRESSION 6750@end example 6751 6752This pragma is identical in effect to pragma @code{Common_Object}. 6753 6754@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 6755@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{c9} 6756@section Pragma Pure_Function 6757 6758 6759Syntax: 6760 6761@example 6762pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 6763@end example 6764 6765This pragma appears in the same declarative part as a function 6766declaration (or a set of function declarations if more than one 6767overloaded declaration exists, in which case the pragma applies 6768to all entities). It specifies that the function @code{Entity} is 6769to be considered pure for the purposes of code generation. This means 6770that the compiler can assume that there are no side effects, and 6771in particular that two calls with identical arguments produce the 6772same result. It also means that the function can be used in an 6773address clause. 6774 6775Note that, quite deliberately, there are no static checks to try 6776to ensure that this promise is met, so @code{Pure_Function} can be used 6777with functions that are conceptually pure, even if they do modify 6778global variables. For example, a square root function that is 6779instrumented to count the number of times it is called is still 6780conceptually pure, and can still be optimized, even though it 6781modifies a global variable (the count). Memo functions are another 6782example (where a table of previous calls is kept and consulted to 6783avoid re-computation). 6784 6785Note also that the normal rules excluding optimization of subprograms 6786in pure units (when parameter types are descended from System.Address, 6787or when the full view of a parameter type is limited), do not apply 6788for the Pure_Function case. If you explicitly specify Pure_Function, 6789the compiler may optimize away calls with identical arguments, and 6790if that results in unexpected behavior, the proper action is not to 6791use the pragma for subprograms that are not (conceptually) pure. 6792 6793Note: Most functions in a @code{Pure} package are automatically pure, and 6794there is no need to use pragma @code{Pure_Function} for such functions. One 6795exception is any function that has at least one formal of type 6796@code{System.Address} or a type derived from it. Such functions are not 6797considered pure by default, since the compiler assumes that the 6798@code{Address} parameter may be functioning as a pointer and that the 6799referenced data may change even if the address value does not. 6800Similarly, imported functions are not considered to be pure by default, 6801since there is no way of checking that they are in fact pure. The use 6802of pragma @code{Pure_Function} for such a function will override these default 6803assumption, and cause the compiler to treat a designated subprogram as pure 6804in these cases. 6805 6806Note: If pragma @code{Pure_Function} is applied to a renamed function, it 6807applies to the underlying renamed function. This can be used to 6808disambiguate cases of overloading where some but not all functions 6809in a set of overloaded functions are to be designated as pure. 6810 6811If pragma @code{Pure_Function} is applied to a library-level function, the 6812function is also considered pure from an optimization point of view, but the 6813unit is not a Pure unit in the categorization sense. So for example, a function 6814thus marked is free to @code{with} non-pure units. 6815 6816@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 6817@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ca} 6818@section Pragma Rational 6819 6820 6821Syntax: 6822 6823@example 6824pragma Rational; 6825@end example 6826 6827This pragma is considered obsolescent, but is retained for 6828compatibility purposes. It is equivalent to: 6829 6830@example 6831pragma Profile (Rational); 6832@end example 6833 6834@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 6835@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb} 6836@section Pragma Ravenscar 6837 6838 6839Syntax: 6840 6841@example 6842pragma Ravenscar; 6843@end example 6844 6845This pragma is considered obsolescent, but is retained for 6846compatibility purposes. It is equivalent to: 6847 6848@example 6849pragma Profile (Ravenscar); 6850@end example 6851 6852which is the preferred method of setting the @code{Ravenscar} profile. 6853 6854@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 6855@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{cd} 6856@section Pragma Refined_Depends 6857 6858 6859Syntax: 6860 6861@example 6862pragma Refined_Depends (DEPENDENCY_RELATION); 6863 6864DEPENDENCY_RELATION ::= 6865 null 6866 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 6867 6868DEPENDENCY_CLAUSE ::= 6869 OUTPUT_LIST =>[+] INPUT_LIST 6870 | NULL_DEPENDENCY_CLAUSE 6871 6872NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 6873 6874OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 6875 6876INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 6877 6878OUTPUT ::= NAME | FUNCTION_RESULT 6879INPUT ::= NAME 6880 6881where FUNCTION_RESULT is a function Result attribute_reference 6882@end example 6883 6884For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in 6885the SPARK 2014 Reference Manual, section 6.1.5. 6886 6887@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 6888@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cf} 6889@section Pragma Refined_Global 6890 6891 6892Syntax: 6893 6894@example 6895pragma Refined_Global (GLOBAL_SPECIFICATION); 6896 6897GLOBAL_SPECIFICATION ::= 6898 null 6899 | (GLOBAL_LIST) 6900 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 6901 6902MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 6903 6904MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 6905GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 6906GLOBAL_ITEM ::= NAME 6907@end example 6908 6909For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in 6910the SPARK 2014 Reference Manual, section 6.1.4. 6911 6912@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 6913@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d1} 6914@section Pragma Refined_Post 6915 6916 6917Syntax: 6918 6919@example 6920pragma Refined_Post (boolean_EXPRESSION); 6921@end example 6922 6923For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in 6924the SPARK 2014 Reference Manual, section 7.2.7. 6925 6926@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 6927@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d3} 6928@section Pragma Refined_State 6929 6930 6931Syntax: 6932 6933@example 6934pragma Refined_State (REFINEMENT_LIST); 6935 6936REFINEMENT_LIST ::= 6937 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 6938 6939REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 6940 6941CONSTITUENT_LIST ::= 6942 null 6943 | CONSTITUENT 6944 | (CONSTITUENT @{, CONSTITUENT@}) 6945 6946CONSTITUENT ::= object_NAME | state_NAME 6947@end example 6948 6949For the semantics of this pragma, see the entry for aspect @code{Refined_State} in 6950the SPARK 2014 Reference Manual, section 7.2.2. 6951 6952@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 6953@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d4} 6954@section Pragma Relative_Deadline 6955 6956 6957Syntax: 6958 6959@example 6960pragma Relative_Deadline (time_span_EXPRESSION); 6961@end example 6962 6963This pragma is standard in Ada 2005, but is available in all earlier 6964versions of Ada as an implementation-defined pragma. 6965See Ada 2012 Reference Manual for details. 6966 6967@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas 6968@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6} 6969@section Pragma Remote_Access_Type 6970 6971 6972Syntax: 6973 6974@example 6975pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 6976@end example 6977 6978This pragma appears in the formal part of a generic declaration. 6979It specifies an exception to the RM rule from E.2.2(17/2), which forbids 6980the use of a remote access to class-wide type as actual for a formal 6981access type. 6982 6983When this pragma applies to a formal access type @code{Entity}, that 6984type is treated as a remote access to class-wide type in the generic. 6985It must be a formal general access type, and its designated type must 6986be the class-wide type of a formal tagged limited private type from the 6987same generic declaration. 6988 6989In the generic unit, the formal type is subject to all restrictions 6990pertaining to remote access to class-wide types. At instantiation, the 6991actual type must be a remote access to class-wide type. 6992 6993@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas 6994@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d7} 6995@section Pragma Restricted_Run_Time 6996 6997 6998Syntax: 6999 7000@example 7001pragma Restricted_Run_Time; 7002@end example 7003 7004This pragma is considered obsolescent, but is retained for 7005compatibility purposes. It is equivalent to: 7006 7007@example 7008pragma Profile (Restricted); 7009@end example 7010 7011which is the preferred method of setting the restricted run time 7012profile. 7013 7014@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 7015@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d8} 7016@section Pragma Restriction_Warnings 7017 7018 7019Syntax: 7020 7021@example 7022pragma Restriction_Warnings 7023 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 7024@end example 7025 7026This pragma allows a series of restriction identifiers to be 7027specified (the list of allowed identifiers is the same as for 7028pragma @code{Restrictions}). For each of these identifiers 7029the compiler checks for violations of the restriction, but 7030generates a warning message rather than an error message 7031if the restriction is violated. 7032 7033One use of this is in situations where you want to know 7034about violations of a restriction, but you want to ignore some of 7035these violations. Consider this example, where you want to set 7036Ada_95 mode and enable style checks, but you want to know about 7037any other use of implementation pragmas: 7038 7039@example 7040pragma Restriction_Warnings (No_Implementation_Pragmas); 7041pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 7042pragma Ada_95; 7043pragma Style_Checks ("2bfhkM160"); 7044pragma Warnings (On, "violation of No_Implementation_Pragmas"); 7045@end example 7046 7047By including the above lines in a configuration pragmas file, 7048the Ada_95 and Style_Checks pragmas are accepted without 7049generating a warning, but any other use of implementation 7050defined pragmas will cause a warning to be generated. 7051 7052@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas 7053@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{d9} 7054@section Pragma Reviewable 7055 7056 7057Syntax: 7058 7059@example 7060pragma Reviewable; 7061@end example 7062 7063This pragma is an RM-defined standard pragma, but has no effect on the 7064program being compiled, or on the code generated for the program. 7065 7066To obtain the required output specified in RM H.3.1, the compiler must be 7067run with various special switches as follows: 7068 7069 7070@itemize * 7071 7072@item 7073@emph{Where compiler-generated run-time checks remain} 7074 7075The switch @emph{-gnatGL} 7076may be used to list the expanded code in pseudo-Ada form. 7077Runtime checks show up in the listing either as explicit 7078checks or operators marked with @{@} to indicate a check is present. 7079 7080@item 7081@emph{An identification of known exceptions at compile time} 7082 7083If the program is compiled with @emph{-gnatwa}, 7084the compiler warning messages will indicate all cases where the compiler 7085detects that an exception is certain to occur at run time. 7086 7087@item 7088@emph{Possible reads of uninitialized variables} 7089 7090The compiler warns of many such cases, but its output is incomplete. 7091@end itemize 7092 7093 7094A supplemental static analysis tool 7095may be used to obtain a comprehensive list of all 7096possible points at which uninitialized data may be read. 7097 7098 7099@itemize * 7100 7101@item 7102@emph{Where run-time support routines are implicitly invoked} 7103 7104In the output from @emph{-gnatGL}, 7105run-time calls are explicitly listed as calls to the relevant 7106run-time routine. 7107 7108@item 7109@emph{Object code listing} 7110 7111This may be obtained either by using the @emph{-S} switch, 7112or the objdump utility. 7113 7114@item 7115@emph{Constructs known to be erroneous at compile time} 7116 7117These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 7118 7119@item 7120@emph{Stack usage information} 7121 7122Static stack usage data (maximum per-subprogram) can be obtained via the 7123@emph{-fstack-usage} switch to the compiler. 7124Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 7125to gnatbind 7126@end itemize 7127 7128 7129 7130@itemize * 7131 7132@item 7133@emph{Object code listing of entire partition} 7134 7135This can be obtained by compiling the partition with @emph{-S}, 7136or by applying objdump 7137to all the object files that are part of the partition. 7138 7139@item 7140@emph{A description of the run-time model} 7141 7142The full sources of the run-time are available, and the documentation of 7143these routines describes how these run-time routines interface to the 7144underlying operating system facilities. 7145 7146@item 7147@emph{Control and data-flow information} 7148@end itemize 7149 7150 7151A supplemental static analysis tool 7152may be used to obtain complete control and data-flow information, as well as 7153comprehensive messages identifying possible problems based on this 7154information. 7155 7156@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas 7157@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{da}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{db} 7158@section Pragma Secondary_Stack_Size 7159 7160 7161Syntax: 7162 7163@example 7164pragma Secondary_Stack_Size (integer_EXPRESSION); 7165@end example 7166 7167This pragma appears within the task definition of a single task declaration 7168or a task type declaration (like pragma @code{Storage_Size}) and applies to all 7169task objects of that type. The argument specifies the size of the secondary 7170stack to be used by these task objects, and must be of an integer type. The 7171secondary stack is used to handle functions that return a variable-sized 7172result, for example a function returning an unconstrained String. 7173 7174Note this pragma only applies to targets using fixed secondary stacks, like 7175VxWorks 653 and bare board targets, where a fixed block for the 7176secondary stack is allocated from the primary stack of the task. By default, 7177these targets assign a percentage of the primary stack for the secondary stack, 7178as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, 7179an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. 7180 7181For most targets, the pragma does not apply as the secondary stack grows on 7182demand: allocated as a chain of blocks in the heap. The default size of these 7183blocks can be modified via the @code{-D} binder option as described in 7184@cite{GNAT User's Guide}. 7185 7186Note that no check is made to see if the secondary stack can fit inside the 7187primary stack. 7188 7189Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} 7190is in effect. 7191 7192@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas 7193@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{dc} 7194@section Pragma Share_Generic 7195 7196 7197Syntax: 7198 7199@example 7200pragma Share_Generic (GNAME @{, GNAME@}); 7201 7202GNAME ::= generic_unit_NAME | generic_instance_NAME 7203@end example 7204 7205This pragma is provided for compatibility with Dec Ada 83. It has 7206no effect in GNAT (which does not implement shared generics), other 7207than to check that the given names are all names of generic units or 7208generic instances. 7209 7210@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 7211@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dd}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{de} 7212@section Pragma Shared 7213 7214 7215This pragma is provided for compatibility with Ada 83. The syntax and 7216semantics are identical to pragma Atomic. 7217 7218@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 7219@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{df} 7220@section Pragma Short_Circuit_And_Or 7221 7222 7223Syntax: 7224 7225@example 7226pragma Short_Circuit_And_Or; 7227@end example 7228 7229This configuration pragma causes any occurrence of the AND operator applied to 7230operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 7231is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 7232may be useful in the context of certification protocols requiring the use of 7233short-circuited logical operators. If this configuration pragma occurs locally 7234within the file being compiled, it applies only to the file being compiled. 7235There is no requirement that all units in a partition use this option. 7236 7237@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 7238@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e0} 7239@section Pragma Short_Descriptors 7240 7241 7242Syntax: 7243 7244@example 7245pragma Short_Descriptors 7246@end example 7247 7248This pragma is provided for compatibility with other Ada implementations. It 7249is recognized but ignored by all current versions of GNAT. 7250 7251@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 7252@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e2} 7253@section Pragma Simple_Storage_Pool_Type 7254 7255 7256@geindex Storage pool 7257@geindex simple 7258 7259@geindex Simple storage pool 7260 7261Syntax: 7262 7263@example 7264pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 7265@end example 7266 7267A type can be established as a 'simple storage pool type' by applying 7268the representation pragma @code{Simple_Storage_Pool_Type} to the type. 7269A type named in the pragma must be a library-level immutably limited record 7270type or limited tagged type declared immediately within a package declaration. 7271The type can also be a limited private type whose full type is allowed as 7272a simple storage pool type. 7273 7274For a simple storage pool type @code{SSP}, nonabstract primitive subprograms 7275@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 7276are subtype conformant with the following subprogram declarations: 7277 7278@example 7279procedure Allocate 7280 (Pool : in out SSP; 7281 Storage_Address : out System.Address; 7282 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7283 Alignment : System.Storage_Elements.Storage_Count); 7284 7285procedure Deallocate 7286 (Pool : in out SSP; 7287 Storage_Address : System.Address; 7288 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7289 Alignment : System.Storage_Elements.Storage_Count); 7290 7291function Storage_Size (Pool : SSP) 7292 return System.Storage_Elements.Storage_Count; 7293@end example 7294 7295Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 7296@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 7297applying an unchecked deallocation has no effect other than to set its actual 7298parameter to null. If @code{Storage_Size} is not declared, then the 7299@code{Storage_Size} attribute applied to an access type associated with 7300a pool object of type SSP returns zero. Additional operations can be declared 7301for a simple storage pool type (such as for supporting a mark/release 7302storage-management discipline). 7303 7304An object of a simple storage pool type can be associated with an access 7305type by specifying the attribute 7306@ref{e3,,Simple_Storage_Pool}. For example: 7307 7308@example 7309My_Pool : My_Simple_Storage_Pool_Type; 7310 7311type Acc is access My_Data_Type; 7312 7313for Acc'Simple_Storage_Pool use My_Pool; 7314@end example 7315 7316See attribute @ref{e3,,Simple_Storage_Pool} 7317for further details. 7318 7319@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7320@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e4}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e5} 7321@section Pragma Source_File_Name 7322 7323 7324Syntax: 7325 7326@example 7327pragma Source_File_Name ( 7328 [Unit_Name =>] unit_NAME, 7329 Spec_File_Name => STRING_LITERAL, 7330 [Index => INTEGER_LITERAL]); 7331 7332pragma Source_File_Name ( 7333 [Unit_Name =>] unit_NAME, 7334 Body_File_Name => STRING_LITERAL, 7335 [Index => INTEGER_LITERAL]); 7336@end example 7337 7338Use this to override the normal naming convention. It is a configuration 7339pragma, and so has the usual applicability of configuration pragmas 7340(i.e., it applies to either an entire partition, or to all units in a 7341compilation, or to a single unit, depending on how it is used. 7342@code{unit_name} is mapped to @code{file_name_literal}. The identifier for 7343the second argument is required, and indicates whether this is the file 7344name for the spec or for the body. 7345 7346The optional Index argument should be used when a file contains multiple 7347units, and when you do not want to use @code{gnatchop} to separate then 7348into multiple files (which is the recommended procedure to limit the 7349number of recompilations that are needed when some sources change). 7350For instance, if the source file @code{source.ada} contains 7351 7352@example 7353package B is 7354... 7355end B; 7356 7357with B; 7358procedure A is 7359begin 7360 .. 7361end A; 7362@end example 7363 7364you could use the following configuration pragmas: 7365 7366@example 7367pragma Source_File_Name 7368 (B, Spec_File_Name => "source.ada", Index => 1); 7369pragma Source_File_Name 7370 (A, Body_File_Name => "source.ada", Index => 2); 7371@end example 7372 7373Note that the @code{gnatname} utility can also be used to generate those 7374configuration pragmas. 7375 7376Another form of the @code{Source_File_Name} pragma allows 7377the specification of patterns defining alternative file naming schemes 7378to apply to all files. 7379 7380@example 7381pragma Source_File_Name 7382 ( [Spec_File_Name =>] STRING_LITERAL 7383 [,[Casing =>] CASING_SPEC] 7384 [,[Dot_Replacement =>] STRING_LITERAL]); 7385 7386pragma Source_File_Name 7387 ( [Body_File_Name =>] STRING_LITERAL 7388 [,[Casing =>] CASING_SPEC] 7389 [,[Dot_Replacement =>] STRING_LITERAL]); 7390 7391pragma Source_File_Name 7392 ( [Subunit_File_Name =>] STRING_LITERAL 7393 [,[Casing =>] CASING_SPEC] 7394 [,[Dot_Replacement =>] STRING_LITERAL]); 7395 7396CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7397@end example 7398 7399The first argument is a pattern that contains a single asterisk indicating 7400the point at which the unit name is to be inserted in the pattern string 7401to form the file name. The second argument is optional. If present it 7402specifies the casing of the unit name in the resulting file name string. 7403The default is lower case. Finally the third argument allows for systematic 7404replacement of any dots in the unit name by the specified string literal. 7405 7406Note that Source_File_Name pragmas should not be used if you are using 7407project files. The reason for this rule is that the project manager is not 7408aware of these pragmas, and so other tools that use the projet file would not 7409be aware of the intended naming conventions. If you are using project files, 7410file naming is controlled by Source_File_Name_Project pragmas, which are 7411usually supplied automatically by the project manager. A pragma 7412Source_File_Name cannot appear after a @ref{e6,,Pragma Source_File_Name_Project}. 7413 7414For more details on the use of the @code{Source_File_Name} pragma, see the 7415sections on @code{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}. 7416 7417@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7418@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e7} 7419@section Pragma Source_File_Name_Project 7420 7421 7422This pragma has the same syntax and semantics as pragma Source_File_Name. 7423It is only allowed as a stand-alone configuration pragma. 7424It cannot appear after a @ref{e4,,Pragma Source_File_Name}, and 7425most importantly, once pragma Source_File_Name_Project appears, 7426no further Source_File_Name pragmas are allowed. 7427 7428The intention is that Source_File_Name_Project pragmas are always 7429generated by the Project Manager in a manner consistent with the naming 7430specified in a project file, and when naming is controlled in this manner, 7431it is not permissible to attempt to modify this naming scheme using 7432Source_File_Name or Source_File_Name_Project pragmas (which would not be 7433known to the project manager). 7434 7435@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7436@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e8} 7437@section Pragma Source_Reference 7438 7439 7440Syntax: 7441 7442@example 7443pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7444@end example 7445 7446This pragma must appear as the first line of a source file. 7447@code{integer_literal} is the logical line number of the line following 7448the pragma line (for use in error messages and debugging 7449information). @code{string_literal} is a static string constant that 7450specifies the file name to be used in error messages and debugging 7451information. This is most notably used for the output of @code{gnatchop} 7452with the @emph{-r} switch, to make sure that the original unchopped 7453source file is the one referred to. 7454 7455The second argument must be a string literal, it cannot be a static 7456string expression other than a string literal. This is because its value 7457is needed for error messages issued by all phases of the compiler. 7458 7459@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7460@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{e9}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{ea} 7461@section Pragma SPARK_Mode 7462 7463 7464Syntax: 7465 7466@example 7467pragma SPARK_Mode [(On | Off)] ; 7468@end example 7469 7470In general a program can have some parts that are in SPARK 2014 (and 7471follow all the rules in the SPARK Reference Manual), and some parts 7472that are full Ada 2012. 7473 7474The SPARK_Mode pragma is used to identify which parts are in SPARK 74752014 (by default programs are in full Ada). The SPARK_Mode pragma can 7476be used in the following places: 7477 7478 7479@itemize * 7480 7481@item 7482As a configuration pragma, in which case it sets the default mode for 7483all units compiled with this pragma. 7484 7485@item 7486Immediately following a library-level subprogram spec 7487 7488@item 7489Immediately within a library-level package body 7490 7491@item 7492Immediately following the @code{private} keyword of a library-level 7493package spec 7494 7495@item 7496Immediately following the @code{begin} keyword of a library-level 7497package body 7498 7499@item 7500Immediately within a library-level subprogram body 7501@end itemize 7502 7503Normally a subprogram or package spec/body inherits the current mode 7504that is active at the point it is declared. But this can be overridden 7505by pragma within the spec or body as above. 7506 7507The basic consistency rule is that you can't turn SPARK_Mode back 7508@code{On}, once you have explicitly (with a pragma) turned if 7509@code{Off}. So the following rules apply: 7510 7511If a subprogram spec has SPARK_Mode @code{Off}, then the body must 7512also have SPARK_Mode @code{Off}. 7513 7514For a package, we have four parts: 7515 7516 7517@itemize * 7518 7519@item 7520the package public declarations 7521 7522@item 7523the package private part 7524 7525@item 7526the body of the package 7527 7528@item 7529the elaboration code after @code{begin} 7530@end itemize 7531 7532For a package, the rule is that if you explicitly turn SPARK_Mode 7533@code{Off} for any part, then all the following parts must have 7534SPARK_Mode @code{Off}. Note that this may require repeating a pragma 7535SPARK_Mode (@code{Off}) in the body. For example, if we have a 7536configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 7537default everywhere, and one particular package spec has pragma 7538SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 7539the package body. 7540 7541@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7542@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{eb} 7543@section Pragma Static_Elaboration_Desired 7544 7545 7546Syntax: 7547 7548@example 7549pragma Static_Elaboration_Desired; 7550@end example 7551 7552This pragma is used to indicate that the compiler should attempt to initialize 7553statically the objects declared in the library unit to which the pragma applies, 7554when these objects are initialized (explicitly or implicitly) by an aggregate. 7555In the absence of this pragma, aggregates in object declarations are expanded 7556into assignments and loops, even when the aggregate components are static 7557constants. When the aggregate is present the compiler builds a static expression 7558that requires no run-time code, so that the initialized object can be placed in 7559read-only data space. If the components are not static, or the aggregate has 7560more that 100 components, the compiler emits a warning that the pragma cannot 7561be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7562construction of larger aggregates with static components that include an others 7563choice.) 7564 7565@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7566@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ec} 7567@section Pragma Stream_Convert 7568 7569 7570Syntax: 7571 7572@example 7573pragma Stream_Convert ( 7574 [Entity =>] type_LOCAL_NAME, 7575 [Read =>] function_NAME, 7576 [Write =>] function_NAME); 7577@end example 7578 7579This pragma provides an efficient way of providing user-defined stream 7580attributes. Not only is it simpler to use than specifying the attributes 7581directly, but more importantly, it allows the specification to be made in such 7582a way that the predefined unit Ada.Streams is not loaded unless it is actually 7583needed (i.e. unless the stream attributes are actually used); the use of 7584the Stream_Convert pragma adds no overhead at all, unless the stream 7585attributes are actually used on the designated type. 7586 7587The first argument specifies the type for which stream functions are 7588provided. The second parameter provides a function used to read values 7589of this type. It must name a function whose argument type may be any 7590subtype, and whose returned type must be the type given as the first 7591argument to the pragma. 7592 7593The meaning of the @code{Read} parameter is that if a stream attribute directly 7594or indirectly specifies reading of the type given as the first parameter, 7595then a value of the type given as the argument to the Read function is 7596read from the stream, and then the Read function is used to convert this 7597to the required target type. 7598 7599Similarly the @code{Write} parameter specifies how to treat write attributes 7600that directly or indirectly apply to the type given as the first parameter. 7601It must have an input parameter of the type specified by the first parameter, 7602and the return type must be the same as the input type of the Read function. 7603The effect is to first call the Write function to convert to the given stream 7604type, and then write the result type to the stream. 7605 7606The Read and Write functions must not be overloaded subprograms. If necessary 7607renamings can be supplied to meet this requirement. 7608The usage of this attribute is best illustrated by a simple example, taken 7609from the GNAT implementation of package Ada.Strings.Unbounded: 7610 7611@example 7612function To_Unbounded (S : String) return Unbounded_String 7613 renames To_Unbounded_String; 7614 7615pragma Stream_Convert 7616 (Unbounded_String, To_Unbounded, To_String); 7617@end example 7618 7619The specifications of the referenced functions, as given in the Ada 7620Reference Manual are: 7621 7622@example 7623function To_Unbounded_String (Source : String) 7624 return Unbounded_String; 7625 7626function To_String (Source : Unbounded_String) 7627 return String; 7628@end example 7629 7630The effect is that if the value of an unbounded string is written to a stream, 7631then the representation of the item in the stream is in the same format that 7632would be used for @code{Standard.String'Output}, and this same representation 7633is expected when a value of this type is read from the stream. Note that the 7634value written always includes the bounds, even for Unbounded_String'Write, 7635since Unbounded_String is not an array type. 7636 7637Note that the @code{Stream_Convert} pragma is not effective in the case of 7638a derived type of a non-limited tagged type. If such a type is specified then 7639the pragma is silently ignored, and the default implementation of the stream 7640attributes is used instead. 7641 7642@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7643@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ed} 7644@section Pragma Style_Checks 7645 7646 7647Syntax: 7648 7649@example 7650pragma Style_Checks (string_LITERAL | ALL_CHECKS | 7651 On | Off [, LOCAL_NAME]); 7652@end example 7653 7654This pragma is used in conjunction with compiler switches to control the 7655built in style checking provided by GNAT. The compiler switches, if set, 7656provide an initial setting for the switches, and this pragma may be used 7657to modify these settings, or the settings may be provided entirely by 7658the use of the pragma. This pragma can be used anywhere that a pragma 7659is legal, including use as a configuration pragma (including use in 7660the @code{gnat.adc} file). 7661 7662The form with a string literal specifies which style options are to be 7663activated. These are additive, so they apply in addition to any previously 7664set style check options. The codes for the options are the same as those 7665used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 7666For example the following two methods can be used to enable 7667layout checking: 7668 7669 7670@itemize * 7671 7672@item 7673@example 7674pragma Style_Checks ("l"); 7675@end example 7676 7677@item 7678@example 7679gcc -c -gnatyl ... 7680@end example 7681@end itemize 7682 7683The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent 7684to the use of the @code{gnaty} switch with no options. 7685See the @cite{GNAT User's Guide} for details.) 7686 7687Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). 7688In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check 7689options (i.e. equivalent to @code{-gnatyg}). 7690 7691The forms with @code{Off} and @code{On} 7692can be used to temporarily disable style checks 7693as shown in the following example: 7694 7695@example 7696pragma Style_Checks ("k"); -- requires keywords in lower case 7697pragma Style_Checks (Off); -- turn off style checks 7698NULL; -- this will not generate an error message 7699pragma Style_Checks (On); -- turn style checks back on 7700NULL; -- this will generate an error message 7701@end example 7702 7703Finally the two argument form is allowed only if the first argument is 7704@code{On} or @code{Off}. The effect is to turn of semantic style checks 7705for the specified entity, as shown in the following example: 7706 7707@example 7708pragma Style_Checks ("r"); -- require consistency of identifier casing 7709Arg : Integer; 7710Rf1 : Integer := ARG; -- incorrect, wrong case 7711pragma Style_Checks (Off, Arg); 7712Rf2 : Integer := ARG; -- OK, no error 7713@end example 7714 7715@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 7716@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ee} 7717@section Pragma Subtitle 7718 7719 7720Syntax: 7721 7722@example 7723pragma Subtitle ([Subtitle =>] STRING_LITERAL); 7724@end example 7725 7726This pragma is recognized for compatibility with other Ada compilers 7727but is ignored by GNAT. 7728 7729@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 7730@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{ef} 7731@section Pragma Suppress 7732 7733 7734Syntax: 7735 7736@example 7737pragma Suppress (Identifier [, [On =>] Name]); 7738@end example 7739 7740This is a standard pragma, and supports all the check names required in 7741the RM. It is included here because GNAT recognizes some additional check 7742names that are implementation defined (as permitted by the RM): 7743 7744 7745@itemize * 7746 7747@item 7748@code{Alignment_Check} can be used to suppress alignment checks 7749on addresses used in address clauses. Such checks can also be suppressed 7750by suppressing range checks, but the specific use of @code{Alignment_Check} 7751allows suppression of alignment checks without suppressing other range checks. 7752Note that @code{Alignment_Check} is suppressed by default on machines (such as 7753the x86) with non-strict alignment. 7754 7755@item 7756@code{Atomic_Synchronization} can be used to suppress the special memory 7757synchronization instructions that are normally generated for access to 7758@code{Atomic} variables to ensure correct synchronization between tasks 7759that use such variables for synchronization purposes. 7760 7761@item 7762@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated 7763for a duplicated tag value when a tagged type is declared. 7764 7765@item 7766@code{Container_Checks} Can be used to suppress all checks within Ada.Containers 7767and instances of its children, including Tampering_Check. 7768 7769@item 7770@code{Tampering_Check} Can be used to suppress tampering check in the containers. 7771 7772@item 7773@code{Predicate_Check} can be used to control whether predicate checks are 7774active. It is applicable only to predicates for which the policy is 7775@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 7776predicate is ignored or checked for the whole program, the use of 7777@code{Suppress} and @code{Unsuppress} with this check name allows a given 7778predicate to be turned on and off at specific points in the program. 7779 7780@item 7781@code{Validity_Check} can be used specifically to control validity checks. 7782If @code{Suppress} is used to suppress validity checks, then no validity 7783checks are performed, including those specified by the appropriate compiler 7784switch or the @code{Validity_Checks} pragma. 7785 7786@item 7787Additional check names previously introduced by use of the @code{Check_Name} 7788pragma are also allowed. 7789@end itemize 7790 7791Note that pragma Suppress gives the compiler permission to omit 7792checks, but does not require the compiler to omit checks. The compiler 7793will generate checks if they are essentially free, even when they are 7794suppressed. In particular, if the compiler can prove that a certain 7795check will necessarily fail, it will generate code to do an 7796unconditional 'raise', even if checks are suppressed. The compiler 7797warns in this case. 7798 7799Of course, run-time checks are omitted whenever the compiler can prove 7800that they will not fail, whether or not checks are suppressed. 7801 7802@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 7803@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f0} 7804@section Pragma Suppress_All 7805 7806 7807Syntax: 7808 7809@example 7810pragma Suppress_All; 7811@end example 7812 7813This pragma can appear anywhere within a unit. 7814The effect is to apply @code{Suppress (All_Checks)} to the unit 7815in which it appears. This pragma is implemented for compatibility with DEC 7816Ada 83 usage where it appears at the end of a unit, and for compatibility 7817with Rational Ada, where it appears as a program unit pragma. 7818The use of the standard Ada pragma @code{Suppress (All_Checks)} 7819as a normal configuration pragma is the preferred usage in GNAT. 7820 7821@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 7822@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f1}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f2} 7823@section Pragma Suppress_Debug_Info 7824 7825 7826Syntax: 7827 7828@example 7829pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 7830@end example 7831 7832This pragma can be used to suppress generation of debug information 7833for the specified entity. It is intended primarily for use in debugging 7834the debugger, and navigating around debugger problems. 7835 7836@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 7837@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f3} 7838@section Pragma Suppress_Exception_Locations 7839 7840 7841Syntax: 7842 7843@example 7844pragma Suppress_Exception_Locations; 7845@end example 7846 7847In normal mode, a raise statement for an exception by default generates 7848an exception message giving the file name and line number for the location 7849of the raise. This is useful for debugging and logging purposes, but this 7850entails extra space for the strings for the messages. The configuration 7851pragma @code{Suppress_Exception_Locations} can be used to suppress the 7852generation of these strings, with the result that space is saved, but the 7853exception message for such raises is null. This configuration pragma may 7854appear in a global configuration pragma file, or in a specific unit as 7855usual. It is not required that this pragma be used consistently within 7856a partition, so it is fine to have some units within a partition compiled 7857with this pragma and others compiled in normal mode without it. 7858 7859@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 7860@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f4}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f5} 7861@section Pragma Suppress_Initialization 7862 7863 7864@geindex Suppressing initialization 7865 7866@geindex Initialization 7867@geindex suppression of 7868 7869Syntax: 7870 7871@example 7872pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 7873@end example 7874 7875Here variable_or_subtype_Name is the name introduced by a type declaration 7876or subtype declaration or the name of a variable introduced by an 7877object declaration. 7878 7879In the case of a type or subtype 7880this pragma suppresses any implicit or explicit initialization 7881for all variables of the given type or subtype, 7882including initialization resulting from the use of pragmas 7883Normalize_Scalars or Initialize_Scalars. 7884 7885This is considered a representation item, so it cannot be given after 7886the type is frozen. It applies to all subsequent object declarations, 7887and also any allocator that creates objects of the type. 7888 7889If the pragma is given for the first subtype, then it is considered 7890to apply to the base type and all its subtypes. If the pragma is given 7891for other than a first subtype, then it applies only to the given subtype. 7892The pragma may not be given after the type is frozen. 7893 7894Note that this includes eliminating initialization of discriminants 7895for discriminated types, and tags for tagged types. In these cases, 7896you will have to use some non-portable mechanism (e.g. address 7897overlays or unchecked conversion) to achieve required initialization 7898of these fields before accessing any object of the corresponding type. 7899 7900For the variable case, implicit initialization for the named variable 7901is suppressed, just as though its subtype had been given in a pragma 7902Suppress_Initialization, as described above. 7903 7904@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 7905@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f6} 7906@section Pragma Task_Name 7907 7908 7909Syntax 7910 7911@example 7912pragma Task_Name (string_EXPRESSION); 7913@end example 7914 7915This pragma appears within a task definition (like pragma 7916@code{Priority}) and applies to the task in which it appears. The 7917argument must be of type String, and provides a name to be used for 7918the task instance when the task is created. Note that this expression 7919is not required to be static, and in particular, it can contain 7920references to task discriminants. This facility can be used to 7921provide different names for different tasks as they are created, 7922as illustrated in the example below. 7923 7924The task name is recorded internally in the run-time structures 7925and is accessible to tools like the debugger. In addition the 7926routine @code{Ada.Task_Identification.Image} will return this 7927string, with a unique task address appended. 7928 7929@example 7930-- Example of the use of pragma Task_Name 7931 7932with Ada.Task_Identification; 7933use Ada.Task_Identification; 7934with Text_IO; use Text_IO; 7935procedure t3 is 7936 7937 type Astring is access String; 7938 7939 task type Task_Typ (Name : access String) is 7940 pragma Task_Name (Name.all); 7941 end Task_Typ; 7942 7943 task body Task_Typ is 7944 Nam : constant String := Image (Current_Task); 7945 begin 7946 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 7947 end Task_Typ; 7948 7949 type Ptr_Task is access Task_Typ; 7950 Task_Var : Ptr_Task; 7951 7952begin 7953 Task_Var := 7954 new Task_Typ (new String'("This is task 1")); 7955 Task_Var := 7956 new Task_Typ (new String'("This is task 2")); 7957end; 7958@end example 7959 7960@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 7961@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f7} 7962@section Pragma Task_Storage 7963 7964 7965Syntax: 7966 7967@example 7968pragma Task_Storage ( 7969 [Task_Type =>] LOCAL_NAME, 7970 [Top_Guard =>] static_integer_EXPRESSION); 7971@end example 7972 7973This pragma specifies the length of the guard area for tasks. The guard 7974area is an additional storage area allocated to a task. A value of zero 7975means that either no guard area is created or a minimal guard area is 7976created, depending on the target. This pragma can appear anywhere a 7977@code{Storage_Size} attribute definition clause is allowed for a task 7978type. 7979 7980@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 7981@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{f8}@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f9} 7982@section Pragma Test_Case 7983 7984 7985@geindex Test cases 7986 7987Syntax: 7988 7989@example 7990pragma Test_Case ( 7991 [Name =>] static_string_Expression 7992 ,[Mode =>] (Nominal | Robustness) 7993 [, Requires => Boolean_Expression] 7994 [, Ensures => Boolean_Expression]); 7995@end example 7996 7997The @code{Test_Case} pragma allows defining fine-grain specifications 7998for use by testing tools. 7999The compiler checks the validity of the @code{Test_Case} pragma, but its 8000presence does not lead to any modification of the code generated by the 8001compiler. 8002 8003@code{Test_Case} pragmas may only appear immediately following the 8004(separate) declaration of a subprogram in a package declaration, inside 8005a package spec unit. Only other pragmas may intervene (that is appear 8006between the subprogram declaration and a test case). 8007 8008The compiler checks that boolean expressions given in @code{Requires} and 8009@code{Ensures} are valid, where the rules for @code{Requires} are the 8010same as the rule for an expression in @code{Precondition} and the rules 8011for @code{Ensures} are the same as the rule for an expression in 8012@code{Postcondition}. In particular, attributes @code{'Old} and 8013@code{'Result} can only be used within the @code{Ensures} 8014expression. The following is an example of use within a package spec: 8015 8016@example 8017package Math_Functions is 8018 ... 8019 function Sqrt (Arg : Float) return Float; 8020 pragma Test_Case (Name => "Test 1", 8021 Mode => Nominal, 8022 Requires => Arg < 10000, 8023 Ensures => Sqrt'Result < 10); 8024 ... 8025end Math_Functions; 8026@end example 8027 8028The meaning of a test case is that there is at least one context where 8029@code{Requires} holds such that, if the associated subprogram is executed in 8030that context, then @code{Ensures} holds when the subprogram returns. 8031Mode @code{Nominal} indicates that the input context should also satisfy the 8032precondition of the subprogram, and the output context should also satisfy its 8033postcondition. Mode @code{Robustness} indicates that the precondition and 8034postcondition of the subprogram should be ignored for this test case. 8035 8036@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 8037@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fb} 8038@section Pragma Thread_Local_Storage 8039 8040 8041@geindex Task specific storage 8042 8043@geindex TLS (Thread Local Storage) 8044 8045@geindex Task_Attributes 8046 8047Syntax: 8048 8049@example 8050pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 8051@end example 8052 8053This pragma specifies that the specified entity, which must be 8054a variable declared in a library-level package, is to be marked as 8055"Thread Local Storage" (@code{TLS}). On systems supporting this (which 8056include Windows, Solaris, GNU/Linux and VxWorks 6), this causes each 8057thread (and hence each Ada task) to see a distinct copy of the variable. 8058 8059The variable may not have default initialization, and if there is 8060an explicit initialization, it must be either @code{null} for an 8061access variable, or a static expression for a scalar variable. 8062This provides a low level mechanism similar to that provided by 8063the @code{Ada.Task_Attributes} package, but much more efficient 8064and is also useful in writing interface code that will interact 8065with foreign threads. 8066 8067If this pragma is used on a system where @code{TLS} is not supported, 8068then an error message will be generated and the program will be rejected. 8069 8070@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 8071@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fc} 8072@section Pragma Time_Slice 8073 8074 8075Syntax: 8076 8077@example 8078pragma Time_Slice (static_duration_EXPRESSION); 8079@end example 8080 8081For implementations of GNAT on operating systems where it is possible 8082to supply a time slice value, this pragma may be used for this purpose. 8083It is ignored if it is used in a system that does not allow this control, 8084or if it appears in other than the main program unit. 8085 8086@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 8087@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fd} 8088@section Pragma Title 8089 8090 8091Syntax: 8092 8093@example 8094pragma Title (TITLING_OPTION [, TITLING OPTION]); 8095 8096TITLING_OPTION ::= 8097 [Title =>] STRING_LITERAL, 8098| [Subtitle =>] STRING_LITERAL 8099@end example 8100 8101Syntax checked but otherwise ignored by GNAT. This is a listing control 8102pragma used in DEC Ada 83 implementations to provide a title and/or 8103subtitle for the program listing. The program listing generated by GNAT 8104does not have titles or subtitles. 8105 8106Unlike other pragmas, the full flexibility of named notation is allowed 8107for this pragma, i.e., the parameters may be given in any order if named 8108notation is used, and named and positional notation can be mixed 8109following the normal rules for procedure calls in Ada. 8110 8111@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 8112@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{fe} 8113@section Pragma Type_Invariant 8114 8115 8116Syntax: 8117 8118@example 8119pragma Type_Invariant 8120 ([Entity =>] type_LOCAL_NAME, 8121 [Check =>] EXPRESSION); 8122@end example 8123 8124The @code{Type_Invariant} pragma is intended to be an exact 8125replacement for the language-defined @code{Type_Invariant} 8126aspect, and shares its restrictions and semantics. It differs 8127from the language defined @code{Invariant} pragma in that it 8128does not permit a string parameter, and it is 8129controlled by the assertion identifier @code{Type_Invariant} 8130rather than @code{Invariant}. 8131 8132@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 8133@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{ff}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{100} 8134@section Pragma Type_Invariant_Class 8135 8136 8137Syntax: 8138 8139@example 8140pragma Type_Invariant_Class 8141 ([Entity =>] type_LOCAL_NAME, 8142 [Check =>] EXPRESSION); 8143@end example 8144 8145The @code{Type_Invariant_Class} pragma is intended to be an exact 8146replacement for the language-defined @code{Type_Invariant'Class} 8147aspect, and shares its restrictions and semantics. 8148 8149Note: This pragma is called @code{Type_Invariant_Class} rather than 8150@code{Type_Invariant'Class} because the latter would not be strictly 8151conforming to the allowed syntax for pragmas. The motivation 8152for providing pragmas equivalent to the aspects is to allow a program 8153to be written using the pragmas, and then compiled if necessary 8154using an Ada compiler that does not recognize the pragmas or 8155aspects, but is prepared to ignore the pragmas. The assertion 8156policy that controls this pragma is @code{Type_Invariant'Class}, 8157not @code{Type_Invariant_Class}. 8158 8159@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 8160@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{101} 8161@section Pragma Unchecked_Union 8162 8163 8164@geindex Unions in C 8165 8166Syntax: 8167 8168@example 8169pragma Unchecked_Union (first_subtype_LOCAL_NAME); 8170@end example 8171 8172This pragma is used to specify a representation of a record type that is 8173equivalent to a C union. It was introduced as a GNAT implementation defined 8174pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 8175pragma, making it language defined, and GNAT fully implements this extended 8176version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 8177details, consult the Ada 2012 Reference Manual, section B.3.3. 8178 8179@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 8180@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{102} 8181@section Pragma Unevaluated_Use_Of_Old 8182 8183 8184@geindex Attribute Old 8185 8186@geindex Attribute Loop_Entry 8187 8188@geindex Unevaluated_Use_Of_Old 8189 8190Syntax: 8191 8192@example 8193pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 8194@end example 8195 8196This pragma controls the processing of attributes Old and Loop_Entry. 8197If either of these attributes is used in a potentially unevaluated 8198expression (e.g. the then or else parts of an if expression), then 8199normally this usage is considered illegal if the prefix of the attribute 8200is other than an entity name. The language requires this 8201behavior for Old, and GNAT copies the same rule for Loop_Entry. 8202 8203The reason for this rule is that otherwise, we can have a situation 8204where we save the Old value, and this results in an exception, even 8205though we might not evaluate the attribute. Consider this example: 8206 8207@example 8208package UnevalOld is 8209 K : Character; 8210 procedure U (A : String; C : Boolean) -- ERROR 8211 with Post => (if C then A(1)'Old = K else True); 8212end; 8213@end example 8214 8215If procedure U is called with a string with a lower bound of 2, and 8216C false, then an exception would be raised trying to evaluate A(1) 8217on entry even though the value would not be actually used. 8218 8219Although the rule guarantees against this possibility, it is sometimes 8220too restrictive. For example if we know that the string has a lower 8221bound of 1, then we will never raise an exception. 8222The pragma @code{Unevaluated_Use_Of_Old} can be 8223used to modify this behavior. If the argument is @code{Error} then an 8224error is given (this is the default RM behavior). If the argument is 8225@code{Warn} then the usage is allowed as legal but with a warning 8226that an exception might be raised. If the argument is @code{Allow} 8227then the usage is allowed as legal without generating a warning. 8228 8229This pragma may appear as a configuration pragma, or in a declarative 8230part or package specification. In the latter case it applies to 8231uses up to the end of the corresponding statement sequence or 8232sequence of package declarations. 8233 8234@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 8235@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{103} 8236@section Pragma Unimplemented_Unit 8237 8238 8239Syntax: 8240 8241@example 8242pragma Unimplemented_Unit; 8243@end example 8244 8245If this pragma occurs in a unit that is processed by the compiler, GNAT 8246aborts with the message @code{xxx not implemented}, where 8247@code{xxx} is the name of the current compilation unit. This pragma is 8248intended to allow the compiler to handle unimplemented library units in 8249a clean manner. 8250 8251The abort only happens if code is being generated. Thus you can use 8252specs of unimplemented packages in syntax or semantic checking mode. 8253 8254@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas 8255@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{104}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{105} 8256@section Pragma Universal_Aliasing 8257 8258 8259Syntax: 8260 8261@example 8262pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 8263@end example 8264 8265@code{type_LOCAL_NAME} must refer to a type declaration in the current 8266declarative part. The effect is to inhibit strict type-based aliasing 8267optimization for the given type. In other words, the effect is as though 8268access types designating this type were subject to pragma No_Strict_Aliasing. 8269For a detailed description of the strict aliasing optimization, and the 8270situations in which it must be suppressed, see the section on 8271@code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}. 8272 8273@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas 8274@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{107} 8275@section Pragma Universal_Data 8276 8277 8278Syntax: 8279 8280@example 8281pragma Universal_Data [(library_unit_Name)]; 8282@end example 8283 8284This pragma is supported only for the AAMP target and is ignored for 8285other targets. The pragma specifies that all library-level objects 8286(Counter 0 data) associated with the library unit are to be accessed 8287and updated using universal addressing (24-bit addresses for AAMP5) 8288rather than the default of 16-bit Data Environment (DENV) addressing. 8289Use of this pragma will generally result in less efficient code for 8290references to global data associated with the library unit, but 8291allows such data to be located anywhere in memory. This pragma is 8292a library unit pragma, but can also be used as a configuration pragma 8293(including use in the @code{gnat.adc} file). The functionality 8294of this pragma is also available by applying the -univ switch on the 8295compilations of units where universal addressing of the data is desired. 8296 8297@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas 8298@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{109} 8299@section Pragma Unmodified 8300 8301 8302@geindex Warnings 8303@geindex unmodified 8304 8305Syntax: 8306 8307@example 8308pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8309@end example 8310 8311This pragma signals that the assignable entities (variables, 8312@code{out} parameters, @code{in out} parameters) whose names are listed are 8313deliberately not assigned in the current source unit. This 8314suppresses warnings about the 8315entities being referenced but not assigned, and in addition a warning will be 8316generated if one of these entities is in fact assigned in the 8317same unit as the pragma (or in the corresponding body, or one 8318of its subunits). 8319 8320This is particularly useful for clearly signaling that a particular 8321parameter is not modified, even though the spec suggests that it might 8322be. 8323 8324For the variable case, warnings are never given for unreferenced variables 8325whose name contains one of the substrings 8326@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8327are typically to be used in cases where such warnings are expected. 8328Thus it is never necessary to use @code{pragma Unmodified} for such 8329variables, though it is harmless to do so. 8330 8331@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8332@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10b} 8333@section Pragma Unreferenced 8334 8335 8336@geindex Warnings 8337@geindex unreferenced 8338 8339Syntax: 8340 8341@example 8342pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8343pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8344@end example 8345 8346This pragma signals that the entities whose names are listed are 8347deliberately not referenced in the current source unit after the 8348occurrence of the pragma. This 8349suppresses warnings about the 8350entities being unreferenced, and in addition a warning will be 8351generated if one of these entities is in fact subsequently referenced in the 8352same unit as the pragma (or in the corresponding body, or one 8353of its subunits). 8354 8355This is particularly useful for clearly signaling that a particular 8356parameter is not referenced in some particular subprogram implementation 8357and that this is deliberate. It can also be useful in the case of 8358objects declared only for their initialization or finalization side 8359effects. 8360 8361If @code{LOCAL_NAME} identifies more than one matching homonym in the 8362current scope, then the entity most recently declared is the one to which 8363the pragma applies. Note that in the case of accept formals, the pragma 8364Unreferenced may appear immediately after the keyword @code{do} which 8365allows the indication of whether or not accept formals are referenced 8366or not to be given individually for each accept statement. 8367 8368The left hand side of an assignment does not count as a reference for the 8369purpose of this pragma. Thus it is fine to assign to an entity for which 8370pragma Unreferenced is given. 8371 8372Note that if a warning is desired for all calls to a given subprogram, 8373regardless of whether they occur in the same unit as the subprogram 8374declaration, then this pragma should not be used (calls from another 8375unit would not be flagged); pragma Obsolescent can be used instead 8376for this purpose, see @ref{a9,,Pragma Obsolescent}. 8377 8378The second form of pragma @code{Unreferenced} is used within a context 8379clause. In this case the arguments must be unit names of units previously 8380mentioned in @code{with} clauses (similar to the usage of pragma 8381@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 8382units and unreferenced entities within these units. 8383 8384For the variable case, warnings are never given for unreferenced variables 8385whose name contains one of the substrings 8386@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8387are typically to be used in cases where such warnings are expected. 8388Thus it is never necessary to use @code{pragma Unreferenced} for such 8389variables, though it is harmless to do so. 8390 8391@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8392@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10d} 8393@section Pragma Unreferenced_Objects 8394 8395 8396@geindex Warnings 8397@geindex unreferenced 8398 8399Syntax: 8400 8401@example 8402pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8403@end example 8404 8405This pragma signals that for the types or subtypes whose names are 8406listed, objects which are declared with one of these types or subtypes may 8407not be referenced, and if no references appear, no warnings are given. 8408 8409This is particularly useful for objects which are declared solely for their 8410initialization and finalization effect. Such variables are sometimes referred 8411to as RAII variables (Resource Acquisition Is Initialization). Using this 8412pragma on the relevant type (most typically a limited controlled type), the 8413compiler will automatically suppress unwanted warnings about these variables 8414not being referenced. 8415 8416@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8417@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10e} 8418@section Pragma Unreserve_All_Interrupts 8419 8420 8421Syntax: 8422 8423@example 8424pragma Unreserve_All_Interrupts; 8425@end example 8426 8427Normally certain interrupts are reserved to the implementation. Any attempt 8428to attach an interrupt causes Program_Error to be raised, as described in 8429RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 8430many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8431reserved to the implementation, so that @code{Ctrl-C} can be used to 8432interrupt execution. 8433 8434If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 8435a program, then all such interrupts are unreserved. This allows the 8436program to handle these interrupts, but disables their standard 8437functions. For example, if this pragma is used, then pressing 8438@code{Ctrl-C} will not automatically interrupt execution. However, 8439a program can then handle the @code{SIGINT} interrupt as it chooses. 8440 8441For a full list of the interrupts handled in a specific implementation, 8442see the source code for the spec of @code{Ada.Interrupts.Names} in 8443file @code{a-intnam.ads}. This is a target dependent file that contains the 8444list of interrupts recognized for a given target. The documentation in 8445this file also specifies what interrupts are affected by the use of 8446the @code{Unreserve_All_Interrupts} pragma. 8447 8448For a more general facility for controlling what interrupts can be 8449handled, see pragma @code{Interrupt_State}, which subsumes the functionality 8450of the @code{Unreserve_All_Interrupts} pragma. 8451 8452@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8453@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10f} 8454@section Pragma Unsuppress 8455 8456 8457Syntax: 8458 8459@example 8460pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8461@end example 8462 8463This pragma undoes the effect of a previous pragma @code{Suppress}. If 8464there is no corresponding pragma @code{Suppress} in effect, it has no 8465effect. The range of the effect is the same as for pragma 8466@code{Suppress}. The meaning of the arguments is identical to that used 8467in pragma @code{Suppress}. 8468 8469One important application is to ensure that checks are on in cases where 8470code depends on the checks for its correct functioning, so that the code 8471will compile correctly even if the compiler switches are set to suppress 8472checks. For example, in a program that depends on external names of tagged 8473types and wants to ensure that the duplicated tag check occurs even if all 8474run-time checks are suppressed by a compiler switch, the following 8475configuration pragma will ensure this test is not suppressed: 8476 8477@example 8478pragma Unsuppress (Duplicated_Tag_Check); 8479@end example 8480 8481This pragma is standard in Ada 2005. It is available in all earlier versions 8482of Ada as an implementation-defined pragma. 8483 8484Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8485number of implementation-defined check names. See the description of pragma 8486@code{Suppress} for full details. 8487 8488@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas 8489@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{110} 8490@section Pragma Use_VADS_Size 8491 8492 8493@geindex Size 8494@geindex VADS compatibility 8495 8496@geindex Rational profile 8497 8498Syntax: 8499 8500@example 8501pragma Use_VADS_Size; 8502@end example 8503 8504This is a configuration pragma. In a unit to which it applies, any use 8505of the 'Size attribute is automatically interpreted as a use of the 8506'VADS_Size attribute. Note that this may result in incorrect semantic 8507processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8508the handling of existing code which depends on the interpretation of Size 8509as implemented in the VADS compiler. See description of the VADS_Size 8510attribute for further details. 8511 8512@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas 8513@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{112} 8514@section Pragma Unused 8515 8516 8517@geindex Warnings 8518@geindex unused 8519 8520Syntax: 8521 8522@example 8523pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); 8524@end example 8525 8526This pragma signals that the assignable entities (variables, 8527@code{out} parameters, and @code{in out} parameters) whose names are listed 8528deliberately do not get assigned or referenced in the current source unit 8529after the occurrence of the pragma in the current source unit. This 8530suppresses warnings about the entities that are unreferenced and/or not 8531assigned, and, in addition, a warning will be generated if one of these 8532entities gets assigned or subsequently referenced in the same unit as the 8533pragma (in the corresponding body or one of its subunits). 8534 8535This is particularly useful for clearly signaling that a particular 8536parameter is not modified or referenced, even though the spec suggests 8537that it might be. 8538 8539For the variable case, warnings are never given for unreferenced 8540variables whose name contains one of the substrings 8541@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8542are typically to be used in cases where such warnings are expected. 8543Thus it is never necessary to use @code{pragma Unmodified} for such 8544variables, though it is harmless to do so. 8545 8546@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas 8547@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{113} 8548@section Pragma Validity_Checks 8549 8550 8551Syntax: 8552 8553@example 8554pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8555@end example 8556 8557This pragma is used in conjunction with compiler switches to control the 8558built-in validity checking provided by GNAT. The compiler switches, if set 8559provide an initial setting for the switches, and this pragma may be used 8560to modify these settings, or the settings may be provided entirely by 8561the use of the pragma. This pragma can be used anywhere that a pragma 8562is legal, including use as a configuration pragma (including use in 8563the @code{gnat.adc} file). 8564 8565The form with a string literal specifies which validity options are to be 8566activated. The validity checks are first set to include only the default 8567reference manual settings, and then a string of letters in the string 8568specifies the exact set of options required. The form of this string 8569is exactly as described for the @emph{-gnatVx} compiler switch (see the 8570GNAT User's Guide for details). For example the following two 8571methods can be used to enable validity checking for mode @code{in} and 8572@code{in out} subprogram parameters: 8573 8574 8575@itemize * 8576 8577@item 8578@example 8579pragma Validity_Checks ("im"); 8580@end example 8581 8582@item 8583@example 8584$ gcc -c -gnatVim ... 8585@end example 8586@end itemize 8587 8588The form ALL_CHECKS activates all standard checks (its use is equivalent 8589to the use of the @code{gnatva} switch. 8590 8591The forms with @code{Off} and @code{On} 8592can be used to temporarily disable validity checks 8593as shown in the following example: 8594 8595@example 8596pragma Validity_Checks ("c"); -- validity checks for copies 8597pragma Validity_Checks (Off); -- turn off validity checks 8598A := B; -- B will not be validity checked 8599pragma Validity_Checks (On); -- turn validity checks back on 8600A := C; -- C will be validity checked 8601@end example 8602 8603@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8604@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114} 8605@section Pragma Volatile 8606 8607 8608Syntax: 8609 8610@example 8611pragma Volatile (LOCAL_NAME); 8612@end example 8613 8614This pragma is defined by the Ada Reference Manual, and the GNAT 8615implementation is fully conformant with this definition. The reason it 8616is mentioned in this section is that a pragma of the same name was supplied 8617in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8618implementation of pragma Volatile is upwards compatible with the 8619implementation in DEC Ada 83. 8620 8621@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8622@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{116} 8623@section Pragma Volatile_Full_Access 8624 8625 8626Syntax: 8627 8628@example 8629pragma Volatile_Full_Access (LOCAL_NAME); 8630@end example 8631 8632This is similar in effect to pragma Volatile, except that any reference to the 8633object is guaranteed to be done only with instructions that read or write all 8634the bits of the object. Furthermore, if the object is of a composite type, 8635then any reference to a component of the object is guaranteed to read and/or 8636write all the bits of the object. 8637 8638The intention is that this be suitable for use with memory-mapped I/O devices 8639on some machines. Note that there are two important respects in which this is 8640different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} 8641object is not a sequential action in the RM 9.10 sense and, therefore, does 8642not create a synchronization point. Second, in the case of @code{pragma Atomic}, 8643there is no guarantee that all the bits will be accessed if the reference 8644is not to the whole object; the compiler is allowed (and generally will) 8645access only part of the object in this case. 8646 8647It is not permissible to specify @code{Atomic} and @code{Volatile_Full_Access} for 8648the same object. 8649 8650It is not permissible to specify @code{Volatile_Full_Access} for a composite 8651(record or array) type or object that has at least one @code{Aliased} component. 8652 8653@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8654@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118} 8655@section Pragma Volatile_Function 8656 8657 8658Syntax: 8659 8660@example 8661pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8662@end example 8663 8664For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} 8665in the SPARK 2014 Reference Manual, section 7.1.2. 8666 8667@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8668@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{119} 8669@section Pragma Warning_As_Error 8670 8671 8672Syntax: 8673 8674@example 8675pragma Warning_As_Error (static_string_EXPRESSION); 8676@end example 8677 8678This configuration pragma allows the programmer to specify a set 8679of warnings that will be treated as errors. Any warning which 8680matches the pattern given by the pragma argument will be treated 8681as an error. This gives much more precise control that -gnatwe 8682which treats all warnings as errors. 8683 8684The pattern may contain asterisks, which match zero or more characters in 8685the message. For example, you can use 8686@code{pragma Warning_As_Error ("bits of*unused")} to treat the warning 8687message @code{warning: 960 bits of "a" unused} as an error. No other regular 8688expression notations are permitted. All characters other than asterisk in 8689these three specific cases are treated as literal characters in the match. 8690The match is case insensitive, for example XYZ matches xyz. 8691 8692Note that the pattern matches if it occurs anywhere within the warning 8693message string (it is not necessary to put an asterisk at the start and 8694the end of the message, since this is implied). 8695 8696Another possibility for the static_string_EXPRESSION which works whether 8697or not error tags are enabled (@emph{-gnatw.d}) is to use the 8698@emph{-gnatw} tag string, enclosed in brackets, 8699as shown in the example below, to treat a class of warnings as errors. 8700 8701The above use of patterns to match the message applies only to warning 8702messages generated by the front end. This pragma can also be applied to 8703warnings provided by the back end and mentioned in @ref{11a,,Pragma Warnings}. 8704By using a single full @emph{-Wxxx} switch in the pragma, such warnings 8705can also be treated as errors. 8706 8707The pragma can appear either in a global configuration pragma file 8708(e.g. @code{gnat.adc}), or at the start of a file. Given a global 8709configuration pragma file containing: 8710 8711@example 8712pragma Warning_As_Error ("[-gnatwj]"); 8713@end example 8714 8715which will treat all obsolescent feature warnings as errors, the 8716following program compiles as shown (compile options here are 8717@emph{-gnatwa.d -gnatl -gnatj55}). 8718 8719@example 8720 1. pragma Warning_As_Error ("*never assigned*"); 8721 2. function Warnerr return String is 8722 3. X : Integer; 8723 | 8724 >>> error: variable "X" is never read and 8725 never assigned [-gnatwv] [warning-as-error] 8726 8727 4. Y : Integer; 8728 | 8729 >>> warning: variable "Y" is assigned but 8730 never read [-gnatwu] 8731 8732 5. begin 8733 6. Y := 0; 8734 7. return %ABC%; 8735 | 8736 >>> error: use of "%" is an obsolescent 8737 feature (RM J.2(4)), use """ instead 8738 [-gnatwj] [warning-as-error] 8739 8740 8. end; 8741 87428 lines: No errors, 3 warnings (2 treated as errors) 8743@end example 8744 8745Note that this pragma does not affect the set of warnings issued in 8746any way, it merely changes the effect of a matching warning if one 8747is produced as a result of other warnings options. As shown in this 8748example, if the pragma results in a warning being treated as an error, 8749the tag is changed from "warning:" to "error:" and the string 8750"[warning-as-error]" is appended to the end of the message. 8751 8752@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 8753@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a} 8754@section Pragma Warnings 8755 8756 8757Syntax: 8758 8759@example 8760pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 8761 8762DETAILS ::= On | Off 8763DETAILS ::= On | Off, local_NAME 8764DETAILS ::= static_string_EXPRESSION 8765DETAILS ::= On | Off, static_string_EXPRESSION 8766 8767TOOL_NAME ::= GNAT | GNATProve 8768 8769REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 8770@end example 8771 8772Note: in Ada 83 mode, a string literal may be used in place of a static string 8773expression (which does not exist in Ada 83). 8774 8775Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the 8776second form is always understood. If the intention is to use 8777the fourth form, then you can write @code{NAME & ""} to force the 8778intepretation as a @emph{static_string_EXPRESSION}. 8779 8780Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted 8781that way. The use of the @code{TOOL_NAME} argument is relevant only to users 8782of SPARK and GNATprove, see last part of this section for details. 8783 8784Normally warnings are enabled, with the output being controlled by 8785the command line switch. Warnings (@code{Off}) turns off generation of 8786warnings until a Warnings (@code{On}) is encountered or the end of the 8787current unit. If generation of warnings is turned off using this 8788pragma, then some or all of the warning messages are suppressed, 8789regardless of the setting of the command line switches. 8790 8791The @code{Reason} parameter may optionally appear as the last argument 8792in any of the forms of this pragma. It is intended purely for the 8793purposes of documenting the reason for the @code{Warnings} pragma. 8794The compiler will check that the argument is a static string but 8795otherwise ignore this argument. Other tools may provide specialized 8796processing for this string. 8797 8798The form with a single argument (or two arguments if Reason present), 8799where the first argument is @code{ON} or @code{OFF} 8800may be used as a configuration pragma. 8801 8802If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for 8803the specified entity. This suppression is effective from the point where 8804it occurs till the end of the extended scope of the variable (similar to 8805the scope of @code{Suppress}). This form cannot be used as a configuration 8806pragma. 8807 8808In the case where the first argument is other than @code{ON} or 8809@code{OFF}, 8810the third form with a single static_string_EXPRESSION argument (and possible 8811reason) provides more precise 8812control over which warnings are active. The string is a list of letters 8813specifying which warnings are to be activated and which deactivated. The 8814code for these letters is the same as the string used in the command 8815line switch controlling warnings. For a brief summary, use the gnatmake 8816command with no arguments, which will generate usage information containing 8817the list of warnings switches supported. For 8818full details see the section on @code{Warning Message Control} in the 8819@cite{GNAT User's Guide}. 8820This form can also be used as a configuration pragma. 8821 8822The warnings controlled by the @code{-gnatw} switch are generated by the 8823front end of the compiler. The GCC back end can provide additional warnings 8824and they are controlled by the @code{-W} switch. Such warnings can be 8825identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the 8826message which designates the @code{-W@emph{xxx}} switch that controls the message. 8827The form with a single @emph{static_string_EXPRESSION} argument also works for these 8828warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this 8829case. The above reference lists a few examples of these additional warnings. 8830 8831The specified warnings will be in effect until the end of the program 8832or another pragma @code{Warnings} is encountered. The effect of the pragma is 8833cumulative. Initially the set of warnings is the standard default set 8834as possibly modified by compiler switches. Then each pragma Warning 8835modifies this set of warnings as specified. This form of the pragma may 8836also be used as a configuration pragma. 8837 8838The fourth form, with an @code{On|Off} parameter and a string, is used to 8839control individual messages, based on their text. The string argument 8840is a pattern that is used to match against the text of individual 8841warning messages (not including the initial "warning: " tag). 8842 8843The pattern may contain asterisks, which match zero or more characters in 8844the message. For example, you can use 8845@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning 8846message @code{warning: 960 bits of "a" unused}. No other regular 8847expression notations are permitted. All characters other than asterisk in 8848these three specific cases are treated as literal characters in the match. 8849The match is case insensitive, for example XYZ matches xyz. 8850 8851Note that the pattern matches if it occurs anywhere within the warning 8852message string (it is not necessary to put an asterisk at the start and 8853the end of the message, since this is implied). 8854 8855The above use of patterns to match the message applies only to warning 8856messages generated by the front end. This form of the pragma with a string 8857argument can also be used to control warnings provided by the back end and 8858mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, 8859such warnings can be turned on and off. 8860 8861There are two ways to use the pragma in this form. The OFF form can be used 8862as a configuration pragma. The effect is to suppress all warnings (if any) 8863that match the pattern string throughout the compilation (or match the 8864-W switch in the back end case). 8865 8866The second usage is to suppress a warning locally, and in this case, two 8867pragmas must appear in sequence: 8868 8869@example 8870pragma Warnings (Off, Pattern); 8871... code where given warning is to be suppressed 8872pragma Warnings (On, Pattern); 8873@end example 8874 8875In this usage, the pattern string must match in the Off and On 8876pragmas, and (if @emph{-gnatw.w} is given) at least one matching 8877warning must be suppressed. 8878 8879Note: to write a string that will match any warning, use the string 8880@code{"***"}. It will not work to use a single asterisk or two 8881asterisks since this looks like an operator name. This form with three 8882asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching 8883@code{pragma Warnings (On, "***")} will be required. This can be 8884helpful in avoiding forgetting to turn warnings back on. 8885 8886Note: the debug flag @code{-gnatd.i} (@code{/NOWARNINGS_PRAGMAS} in VMS) can be 8887used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 8888be useful in checking whether obsolete pragmas in existing programs are hiding 8889real problems. 8890 8891Note: pragma Warnings does not affect the processing of style messages. See 8892separate entry for pragma Style_Checks for control of style messages. 8893 8894Users of the formal verification tool GNATprove for the SPARK subset of Ada may 8895use the version of the pragma with a @code{TOOL_NAME} parameter. 8896 8897If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the 8898compiler or @code{GNATprove} for the formal verification tool. A given tool only 8899takes into account pragma Warnings that do not specify a tool name, or that 8900specify the matching tool name. This makes it possible to disable warnings 8901selectively for each tool, and as a consequence to detect useless pragma 8902Warnings with switch @code{-gnatw.w}. 8903 8904@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 8905@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11c} 8906@section Pragma Weak_External 8907 8908 8909Syntax: 8910 8911@example 8912pragma Weak_External ([Entity =>] LOCAL_NAME); 8913@end example 8914 8915@code{LOCAL_NAME} must refer to an object that is declared at the library 8916level. This pragma specifies that the given entity should be marked as a 8917weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 8918in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead 8919of a regular symbol, that is to say a symbol that does not have to be 8920resolved by the linker if used in conjunction with a pragma Import. 8921 8922When a weak symbol is not resolved by the linker, its address is set to 8923zero. This is useful in writing interfaces to external modules that may 8924or may not be linked in the final executable, for example depending on 8925configuration settings. 8926 8927If a program references at run time an entity to which this pragma has been 8928applied, and the corresponding symbol was not resolved at link time, then 8929the execution of the program is erroneous. It is not erroneous to take the 8930Address of such an entity, for example to guard potential references, 8931as shown in the example below. 8932 8933Some file formats do not support weak symbols so not all target machines 8934support this pragma. 8935 8936@example 8937-- Example of the use of pragma Weak_External 8938 8939package External_Module is 8940 key : Integer; 8941 pragma Import (C, key); 8942 pragma Weak_External (key); 8943 function Present return boolean; 8944end External_Module; 8945 8946with System; use System; 8947package body External_Module is 8948 function Present return boolean is 8949 begin 8950 return key'Address /= System.Null_Address; 8951 end Present; 8952end External_Module; 8953@end example 8954 8955@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 8956@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d} 8957@section Pragma Wide_Character_Encoding 8958 8959 8960Syntax: 8961 8962@example 8963pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 8964@end example 8965 8966This pragma specifies the wide character encoding to be used in program 8967source text appearing subsequently. It is a configuration pragma, but may 8968also be used at any point that a pragma is allowed, and it is permissible 8969to have more than one such pragma in a file, allowing multiple encodings 8970to appear within the same file. 8971 8972However, note that the pragma cannot immediately precede the relevant 8973wide character, because then the previous encoding will still be in 8974effect, causing "illegal character" errors. 8975 8976The argument can be an identifier or a character literal. In the identifier 8977case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 8978@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 8979case it is correspondingly one of the characters @code{h}, @code{u}, 8980@code{s}, @code{e}, @code{8}, or @code{b}. 8981 8982Note that when the pragma is used within a file, it affects only the 8983encoding within that file, and does not affect withed units, specs, 8984or subunits. 8985 8986@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 8987@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{120} 8988@chapter Implementation Defined Aspects 8989 8990 8991Ada defines (throughout the Ada 2012 reference manual, summarized 8992in Annex K) a set of aspects that can be specified for certain entities. 8993These language defined aspects are implemented in GNAT in Ada 2012 mode 8994and work as described in the Ada 2012 Reference Manual. 8995 8996In addition, Ada 2012 allows implementations to define additional aspects 8997whose meaning is defined by the implementation. GNAT provides 8998a number of these implementation-defined aspects which can be used 8999to extend and enhance the functionality of the compiler. This section of 9000the GNAT reference manual describes these additional aspects. 9001 9002Note that any program using these aspects may not be portable to 9003other compilers (although GNAT implements this set of aspects on all 9004platforms). Therefore if portability to other compilers is an important 9005consideration, you should minimize the use of these aspects. 9006 9007Note that for many of these aspects, the effect is essentially similar 9008to the use of a pragma or attribute specification with the same name 9009applied to the entity. For example, if we write: 9010 9011@example 9012type R is range 1 .. 100 9013 with Value_Size => 10; 9014@end example 9015 9016then the effect is the same as: 9017 9018@example 9019type R is range 1 .. 100; 9020for R'Value_Size use 10; 9021@end example 9022 9023and if we write: 9024 9025@example 9026type R is new Integer 9027 with Shared => True; 9028@end example 9029 9030then the effect is the same as: 9031 9032@example 9033type R is new Integer; 9034pragma Shared (R); 9035@end example 9036 9037In the documentation below, such cases are simply marked 9038as being boolean aspects equivalent to the corresponding pragma 9039or attribute definition clause. 9040 9041@menu 9042* Aspect Abstract_State:: 9043* Aspect Annotate:: 9044* Aspect Async_Readers:: 9045* Aspect Async_Writers:: 9046* Aspect Constant_After_Elaboration:: 9047* Aspect Contract_Cases:: 9048* Aspect Depends:: 9049* Aspect Default_Initial_Condition:: 9050* Aspect Dimension:: 9051* Aspect Dimension_System:: 9052* Aspect Disable_Controlled:: 9053* Aspect Effective_Reads:: 9054* Aspect Effective_Writes:: 9055* Aspect Extensions_Visible:: 9056* Aspect Favor_Top_Level:: 9057* Aspect Ghost:: 9058* Aspect Global:: 9059* Aspect Initial_Condition:: 9060* Aspect Initializes:: 9061* Aspect Inline_Always:: 9062* Aspect Invariant:: 9063* Aspect Invariant'Class:: 9064* Aspect Iterable:: 9065* Aspect Linker_Section:: 9066* Aspect Lock_Free:: 9067* Aspect Max_Queue_Length:: 9068* Aspect No_Elaboration_Code_All:: 9069* Aspect No_Inline:: 9070* Aspect No_Tagged_Streams:: 9071* Aspect Object_Size:: 9072* Aspect Obsolescent:: 9073* Aspect Part_Of:: 9074* Aspect Persistent_BSS:: 9075* Aspect Predicate:: 9076* Aspect Pure_Function:: 9077* Aspect Refined_Depends:: 9078* Aspect Refined_Global:: 9079* Aspect Refined_Post:: 9080* Aspect Refined_State:: 9081* Aspect Remote_Access_Type:: 9082* Aspect Secondary_Stack_Size:: 9083* Aspect Scalar_Storage_Order:: 9084* Aspect Shared:: 9085* Aspect Simple_Storage_Pool:: 9086* Aspect Simple_Storage_Pool_Type:: 9087* Aspect SPARK_Mode:: 9088* Aspect Suppress_Debug_Info:: 9089* Aspect Suppress_Initialization:: 9090* Aspect Test_Case:: 9091* Aspect Thread_Local_Storage:: 9092* Aspect Universal_Aliasing:: 9093* Aspect Universal_Data:: 9094* Aspect Unmodified:: 9095* Aspect Unreferenced:: 9096* Aspect Unreferenced_Objects:: 9097* Aspect Value_Size:: 9098* Aspect Volatile_Full_Access:: 9099* Aspect Volatile_Function:: 9100* Aspect Warnings:: 9101 9102@end menu 9103 9104@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects 9105@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121} 9106@section Aspect Abstract_State 9107 9108 9109@geindex Abstract_State 9110 9111This aspect is equivalent to @ref{1c,,pragma Abstract_State}. 9112 9113@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 9114@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122} 9115@section Aspect Annotate 9116 9117 9118@geindex Annotate 9119 9120There are three forms of this aspect (where ID is an identifier, 9121and ARG is a general expression), 9122corresponding to @ref{25,,pragma Annotate}. 9123 9124 9125@table @asis 9126 9127@item @emph{Annotate => ID} 9128 9129Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9130 9131@item @emph{Annotate => (ID)} 9132 9133Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9134 9135@item @emph{Annotate => (ID ,ID @{, ARG@})} 9136 9137Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} 9138@end table 9139 9140@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects 9141@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{123} 9142@section Aspect Async_Readers 9143 9144 9145@geindex Async_Readers 9146 9147This boolean aspect is equivalent to @ref{2c,,pragma Async_Readers}. 9148 9149@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 9150@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{124} 9151@section Aspect Async_Writers 9152 9153 9154@geindex Async_Writers 9155 9156This boolean aspect is equivalent to @ref{2f,,pragma Async_Writers}. 9157 9158@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 9159@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{125} 9160@section Aspect Constant_After_Elaboration 9161 9162 9163@geindex Constant_After_Elaboration 9164 9165This aspect is equivalent to @ref{40,,pragma Constant_After_Elaboration}. 9166 9167@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 9168@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{126} 9169@section Aspect Contract_Cases 9170 9171 9172@geindex Contract_Cases 9173 9174This aspect is equivalent to @ref{42,,pragma Contract_Cases}, the sequence 9175of clauses being enclosed in parentheses so that syntactically it is an 9176aggregate. 9177 9178@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 9179@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127} 9180@section Aspect Depends 9181 9182 9183@geindex Depends 9184 9185This aspect is equivalent to @ref{51,,pragma Depends}. 9186 9187@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 9188@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{128} 9189@section Aspect Default_Initial_Condition 9190 9191 9192@geindex Default_Initial_Condition 9193 9194This aspect is equivalent to @ref{4c,,pragma Default_Initial_Condition}. 9195 9196@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 9197@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{129} 9198@section Aspect Dimension 9199 9200 9201@geindex Dimension 9202 9203The @code{Dimension} aspect is used to specify the dimensions of a given 9204subtype of a dimensioned numeric type. The aspect also specifies a symbol 9205used when doing formatted output of dimensioned quantities. The syntax is: 9206 9207@example 9208with Dimension => 9209 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 9210 9211SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 9212 9213DIMENSION_VALUE ::= 9214 RATIONAL 9215| others => RATIONAL 9216| DISCRETE_CHOICE_LIST => RATIONAL 9217 9218RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 9219@end example 9220 9221This aspect can only be applied to a subtype whose parent type has 9222a @code{Dimension_System} aspect. The aspect must specify values for 9223all dimensions of the system. The rational values are the powers of the 9224corresponding dimensions that are used by the compiler to verify that 9225physical (numeric) computations are dimensionally consistent. For example, 9226the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 9227For further examples of the usage 9228of this aspect, see package @code{System.Dim.Mks}. 9229Note that when the dimensioned type is an integer type, then any 9230dimension value must be an integer literal. 9231 9232@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 9233@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12a} 9234@section Aspect Dimension_System 9235 9236 9237@geindex Dimension_System 9238 9239The @code{Dimension_System} aspect is used to define a system of 9240dimensions that will be used in subsequent subtype declarations with 9241@code{Dimension} aspects that reference this system. The syntax is: 9242 9243@example 9244with Dimension_System => (DIMENSION @{, DIMENSION@}); 9245 9246DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 9247 [Unit_Symbol =>] SYMBOL, 9248 [Dim_Symbol =>] SYMBOL) 9249 9250SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 9251@end example 9252 9253This aspect is applied to a type, which must be a numeric derived type 9254(typically a floating-point type), that 9255will represent values within the dimension system. Each @code{DIMENSION} 9256corresponds to one particular dimension. A maximum of 7 dimensions may 9257be specified. @code{Unit_Name} is the name of the dimension (for example 9258@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 9259of this dimension (for example @code{m} for @code{Meter}). 9260@code{Dim_Symbol} gives 9261the identification within the dimension system (typically this is a 9262single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 9263The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 9264The @code{Dim_Symbol} is used in error messages when numeric operations have 9265inconsistent dimensions. 9266 9267GNAT provides the standard definition of the International MKS system in 9268the run-time package @code{System.Dim.Mks}. You can easily define 9269similar packages for cgs units or British units, and define conversion factors 9270between values in different systems. The MKS system is characterized by the 9271following aspect: 9272 9273@example 9274type Mks_Type is new Long_Long_Float with 9275 Dimension_System => ( 9276 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 9277 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 9278 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 9279 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 9280 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 9281 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 9282 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 9283@end example 9284 9285Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to 9286represent a theta character (avoiding the use of extended Latin-1 9287characters in this context). 9288 9289See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users 9290Guide for detailed examples of use of the dimension system. 9291 9292@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 9293@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12b} 9294@section Aspect Disable_Controlled 9295 9296 9297@geindex Disable_Controlled 9298 9299The aspect @code{Disable_Controlled} is defined for controlled record types. If 9300active, this aspect causes suppression of all related calls to @code{Initialize}, 9301@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, 9302where for example you might want a record to be controlled or not depending on 9303whether some run-time check is enabled or suppressed. 9304 9305@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 9306@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12c} 9307@section Aspect Effective_Reads 9308 9309 9310@geindex Effective_Reads 9311 9312This aspect is equivalent to @ref{57,,pragma Effective_Reads}. 9313 9314@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 9315@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12d} 9316@section Aspect Effective_Writes 9317 9318 9319@geindex Effective_Writes 9320 9321This aspect is equivalent to @ref{59,,pragma Effective_Writes}. 9322 9323@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 9324@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12e} 9325@section Aspect Extensions_Visible 9326 9327 9328@geindex Extensions_Visible 9329 9330This aspect is equivalent to @ref{65,,pragma Extensions_Visible}. 9331 9332@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 9333@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12f} 9334@section Aspect Favor_Top_Level 9335 9336 9337@geindex Favor_Top_Level 9338 9339This boolean aspect is equivalent to @ref{6a,,pragma Favor_Top_Level}. 9340 9341@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9342@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{130} 9343@section Aspect Ghost 9344 9345 9346@geindex Ghost 9347 9348This aspect is equivalent to @ref{6d,,pragma Ghost}. 9349 9350@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9351@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131} 9352@section Aspect Global 9353 9354 9355@geindex Global 9356 9357This aspect is equivalent to @ref{6f,,pragma Global}. 9358 9359@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9360@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132} 9361@section Aspect Initial_Condition 9362 9363 9364@geindex Initial_Condition 9365 9366This aspect is equivalent to @ref{7d,,pragma Initial_Condition}. 9367 9368@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9369@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133} 9370@section Aspect Initializes 9371 9372 9373@geindex Initializes 9374 9375This aspect is equivalent to @ref{7f,,pragma Initializes}. 9376 9377@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9378@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134} 9379@section Aspect Inline_Always 9380 9381 9382@geindex Inline_Always 9383 9384This boolean aspect is equivalent to @ref{82,,pragma Inline_Always}. 9385 9386@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects 9387@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135} 9388@section Aspect Invariant 9389 9390 9391@geindex Invariant 9392 9393This aspect is equivalent to @ref{89,,pragma Invariant}. It is a 9394synonym for the language defined aspect @code{Type_Invariant} except 9395that it is separately controllable using pragma @code{Assertion_Policy}. 9396 9397@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9398@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{136} 9399@section Aspect Invariant'Class 9400 9401 9402@geindex Invariant'Class 9403 9404This aspect is equivalent to @ref{100,,pragma Type_Invariant_Class}. It is a 9405synonym for the language defined aspect @code{Type_Invariant'Class} except 9406that it is separately controllable using pragma @code{Assertion_Policy}. 9407 9408@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects 9409@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{137} 9410@section Aspect Iterable 9411 9412 9413@geindex Iterable 9414 9415This aspect provides a light-weight mechanism for loops and quantified 9416expressions over container types, without the overhead imposed by the tampering 9417checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9418with six named components, of which the last three are optional: @code{First}, 9419@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. 9420When only the first three components are specified, only the 9421@code{for .. in} form of iteration over cursors is available. When @code{Element} 9422is specified, both this form and the @code{for .. of} form of iteration over 9423elements are available. If the last two components are specified, reverse 9424iterations over the container can be specified (analogous to what can be done 9425over predefined containers that support the @code{Reverse_Iterator} interface). 9426The following is a typical example of use: 9427 9428@example 9429type List is private with 9430 Iterable => (First => First_Cursor, 9431 Next => Advance, 9432 Has_Element => Cursor_Has_Element, 9433 [Element => Get_Element]); 9434@end example 9435 9436 9437@itemize * 9438 9439@item 9440The value denoted by @code{First} must denote a primitive operation of the 9441container type that returns a @code{Cursor}, which must a be a type declared in 9442the container package or visible from it. For example: 9443@end itemize 9444 9445@example 9446function First_Cursor (Cont : Container) return Cursor; 9447@end example 9448 9449 9450@itemize * 9451 9452@item 9453The value of @code{Next} is a primitive operation of the container type that takes 9454both a container and a cursor and yields a cursor. For example: 9455@end itemize 9456 9457@example 9458function Advance (Cont : Container; Position : Cursor) return Cursor; 9459@end example 9460 9461 9462@itemize * 9463 9464@item 9465The value of @code{Has_Element} is a primitive operation of the container type 9466that takes both a container and a cursor and yields a boolean. For example: 9467@end itemize 9468 9469@example 9470function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9471@end example 9472 9473 9474@itemize * 9475 9476@item 9477The value of @code{Element} is a primitive operation of the container type that 9478takes both a container and a cursor and yields an @code{Element_Type}, which must 9479be a type declared in the container package or visible from it. For example: 9480@end itemize 9481 9482@example 9483function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9484@end example 9485 9486This aspect is used in the GNAT-defined formal container packages. 9487 9488@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9489@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{138} 9490@section Aspect Linker_Section 9491 9492 9493@geindex Linker_Section 9494 9495This aspect is equivalent to @ref{91,,pragma Linker_Section}. 9496 9497@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects 9498@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{139} 9499@section Aspect Lock_Free 9500 9501 9502@geindex Lock_Free 9503 9504This boolean aspect is equivalent to @ref{93,,pragma Lock_Free}. 9505 9506@node Aspect Max_Queue_Length,Aspect No_Elaboration_Code_All,Aspect Lock_Free,Implementation Defined Aspects 9507@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13a} 9508@section Aspect Max_Queue_Length 9509 9510 9511@geindex Max_Queue_Length 9512 9513This aspect is equivalent to @ref{9b,,pragma Max_Queue_Length}. 9514 9515@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect Max_Queue_Length,Implementation Defined Aspects 9516@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13b} 9517@section Aspect No_Elaboration_Code_All 9518 9519 9520@geindex No_Elaboration_Code_All 9521 9522This aspect is equivalent to @ref{9f,,pragma No_Elaboration_Code_All} 9523for a program unit. 9524 9525@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9526@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13c} 9527@section Aspect No_Inline 9528 9529 9530@geindex No_Inline 9531 9532This boolean aspect is equivalent to @ref{a2,,pragma No_Inline}. 9533 9534@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects 9535@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13d} 9536@section Aspect No_Tagged_Streams 9537 9538 9539@geindex No_Tagged_Streams 9540 9541This aspect is equivalent to @ref{a6,,pragma No_Tagged_Streams} with an 9542argument specifying a root tagged type (thus this aspect can only be 9543applied to such a type). 9544 9545@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects 9546@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{13e} 9547@section Aspect Object_Size 9548 9549 9550@geindex Object_Size 9551 9552This aspect is equivalent to @ref{13f,,attribute Object_Size}. 9553 9554@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9555@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{140} 9556@section Aspect Obsolescent 9557 9558 9559@geindex Obsolsecent 9560 9561This aspect is equivalent to @ref{a9,,pragma Obsolescent}. Note that the 9562evaluation of this aspect happens at the point of occurrence, it is not 9563delayed until the freeze point. 9564 9565@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9566@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{141} 9567@section Aspect Part_Of 9568 9569 9570@geindex Part_Of 9571 9572This aspect is equivalent to @ref{b1,,pragma Part_Of}. 9573 9574@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9575@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{142} 9576@section Aspect Persistent_BSS 9577 9578 9579@geindex Persistent_BSS 9580 9581This boolean aspect is equivalent to @ref{b4,,pragma Persistent_BSS}. 9582 9583@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9584@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{143} 9585@section Aspect Predicate 9586 9587 9588@geindex Predicate 9589 9590This aspect is equivalent to @ref{bd,,pragma Predicate}. It is thus 9591similar to the language defined aspects @code{Dynamic_Predicate} 9592and @code{Static_Predicate} except that whether the resulting 9593predicate is static or dynamic is controlled by the form of the 9594expression. It is also separately controllable using pragma 9595@code{Assertion_Policy}. 9596 9597@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9598@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{144} 9599@section Aspect Pure_Function 9600 9601 9602@geindex Pure_Function 9603 9604This boolean aspect is equivalent to @ref{c8,,pragma Pure_Function}. 9605 9606@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9607@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{145} 9608@section Aspect Refined_Depends 9609 9610 9611@geindex Refined_Depends 9612 9613This aspect is equivalent to @ref{cc,,pragma Refined_Depends}. 9614 9615@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9616@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{146} 9617@section Aspect Refined_Global 9618 9619 9620@geindex Refined_Global 9621 9622This aspect is equivalent to @ref{ce,,pragma Refined_Global}. 9623 9624@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9625@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{147} 9626@section Aspect Refined_Post 9627 9628 9629@geindex Refined_Post 9630 9631This aspect is equivalent to @ref{d0,,pragma Refined_Post}. 9632 9633@node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects 9634@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{148} 9635@section Aspect Refined_State 9636 9637 9638@geindex Refined_State 9639 9640This aspect is equivalent to @ref{d2,,pragma Refined_State}. 9641 9642@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Refined_State,Implementation Defined Aspects 9643@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{149} 9644@section Aspect Remote_Access_Type 9645 9646 9647@geindex Remote_Access_Type 9648 9649This aspect is equivalent to @ref{d6,,pragma Remote_Access_Type}. 9650 9651@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects 9652@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14a} 9653@section Aspect Secondary_Stack_Size 9654 9655 9656@geindex Secondary_Stack_Size 9657 9658This aspect is equivalent to @ref{db,,pragma Secondary_Stack_Size}. 9659 9660@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects 9661@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14b} 9662@section Aspect Scalar_Storage_Order 9663 9664 9665@geindex Scalar_Storage_Order 9666 9667This aspect is equivalent to a @ref{14c,,attribute Scalar_Storage_Order}. 9668 9669@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 9670@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{14d} 9671@section Aspect Shared 9672 9673 9674@geindex Shared 9675 9676This boolean aspect is equivalent to @ref{de,,pragma Shared} 9677and is thus a synonym for aspect @code{Atomic}. 9678 9679@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 9680@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{14e} 9681@section Aspect Simple_Storage_Pool 9682 9683 9684@geindex Simple_Storage_Pool 9685 9686This aspect is equivalent to @ref{e3,,attribute Simple_Storage_Pool}. 9687 9688@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 9689@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{14f} 9690@section Aspect Simple_Storage_Pool_Type 9691 9692 9693@geindex Simple_Storage_Pool_Type 9694 9695This boolean aspect is equivalent to @ref{e1,,pragma Simple_Storage_Pool_Type}. 9696 9697@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 9698@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{150} 9699@section Aspect SPARK_Mode 9700 9701 9702@geindex SPARK_Mode 9703 9704This aspect is equivalent to @ref{e9,,pragma SPARK_Mode} and 9705may be specified for either or both of the specification and body 9706of a subprogram or package. 9707 9708@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 9709@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{151} 9710@section Aspect Suppress_Debug_Info 9711 9712 9713@geindex Suppress_Debug_Info 9714 9715This boolean aspect is equivalent to @ref{f1,,pragma Suppress_Debug_Info}. 9716 9717@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 9718@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{152} 9719@section Aspect Suppress_Initialization 9720 9721 9722@geindex Suppress_Initialization 9723 9724This boolean aspect is equivalent to @ref{f5,,pragma Suppress_Initialization}. 9725 9726@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 9727@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{153} 9728@section Aspect Test_Case 9729 9730 9731@geindex Test_Case 9732 9733This aspect is equivalent to @ref{f8,,pragma Test_Case}. 9734 9735@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 9736@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{154} 9737@section Aspect Thread_Local_Storage 9738 9739 9740@geindex Thread_Local_Storage 9741 9742This boolean aspect is equivalent to @ref{fa,,pragma Thread_Local_Storage}. 9743 9744@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects 9745@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{155} 9746@section Aspect Universal_Aliasing 9747 9748 9749@geindex Universal_Aliasing 9750 9751This boolean aspect is equivalent to @ref{105,,pragma Universal_Aliasing}. 9752 9753@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects 9754@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{156} 9755@section Aspect Universal_Data 9756 9757 9758@geindex Universal_Data 9759 9760This aspect is equivalent to @ref{106,,pragma Universal_Data}. 9761 9762@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects 9763@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{157} 9764@section Aspect Unmodified 9765 9766 9767@geindex Unmodified 9768 9769This boolean aspect is equivalent to @ref{108,,pragma Unmodified}. 9770 9771@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 9772@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{158} 9773@section Aspect Unreferenced 9774 9775 9776@geindex Unreferenced 9777 9778This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}. Note that 9779in the case of formal parameters, it is not permitted to have aspects for 9780a formal parameter, so in this case the pragma form must be used. 9781 9782@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 9783@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{159} 9784@section Aspect Unreferenced_Objects 9785 9786 9787@geindex Unreferenced_Objects 9788 9789This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced_Objects}. 9790 9791@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 9792@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15a} 9793@section Aspect Value_Size 9794 9795 9796@geindex Value_Size 9797 9798This aspect is equivalent to @ref{15b,,attribute Value_Size}. 9799 9800@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 9801@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15c} 9802@section Aspect Volatile_Full_Access 9803 9804 9805@geindex Volatile_Full_Access 9806 9807This boolean aspect is equivalent to @ref{115,,pragma Volatile_Full_Access}. 9808 9809@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 9810@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{15d} 9811@section Aspect Volatile_Function 9812 9813 9814@geindex Volatile_Function 9815 9816This boolean aspect is equivalent to @ref{118,,pragma Volatile_Function}. 9817 9818@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 9819@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{15e} 9820@section Aspect Warnings 9821 9822 9823@geindex Warnings 9824 9825This aspect is equivalent to the two argument form of @ref{11a,,pragma Warnings}, 9826where the first argument is @code{ON} or @code{OFF} and the second argument 9827is the entity. 9828 9829@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 9830@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{15f}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{160} 9831@chapter Implementation Defined Attributes 9832 9833 9834Ada defines (throughout the Ada reference manual, 9835summarized in Annex K), 9836a set of attributes that provide useful additional functionality in all 9837areas of the language. These language defined attributes are implemented 9838in GNAT and work as described in the Ada Reference Manual. 9839 9840In addition, Ada allows implementations to define additional 9841attributes whose meaning is defined by the implementation. GNAT provides 9842a number of these implementation-dependent attributes which can be used 9843to extend and enhance the functionality of the compiler. This section of 9844the GNAT reference manual describes these additional attributes. It also 9845describes additional implementation-dependent features of standard 9846language-defined attributes. 9847 9848Note that any program using these attributes may not be portable to 9849other compilers (although GNAT implements this set of attributes on all 9850platforms). Therefore if portability to other compilers is an important 9851consideration, you should minimize the use of these attributes. 9852 9853@menu 9854* Attribute Abort_Signal:: 9855* Attribute Address_Size:: 9856* Attribute Asm_Input:: 9857* Attribute Asm_Output:: 9858* Attribute Atomic_Always_Lock_Free:: 9859* Attribute Bit:: 9860* Attribute Bit_Position:: 9861* Attribute Code_Address:: 9862* Attribute Compiler_Version:: 9863* Attribute Constrained:: 9864* Attribute Default_Bit_Order:: 9865* Attribute Default_Scalar_Storage_Order:: 9866* Attribute Deref:: 9867* Attribute Descriptor_Size:: 9868* Attribute Elaborated:: 9869* Attribute Elab_Body:: 9870* Attribute Elab_Spec:: 9871* Attribute Elab_Subp_Body:: 9872* Attribute Emax:: 9873* Attribute Enabled:: 9874* Attribute Enum_Rep:: 9875* Attribute Enum_Val:: 9876* Attribute Epsilon:: 9877* Attribute Fast_Math:: 9878* Attribute Finalization_Size:: 9879* Attribute Fixed_Value:: 9880* Attribute From_Any:: 9881* Attribute Has_Access_Values:: 9882* Attribute Has_Discriminants:: 9883* Attribute Img:: 9884* Attribute Integer_Value:: 9885* Attribute Invalid_Value:: 9886* Attribute Iterable:: 9887* Attribute Large:: 9888* Attribute Library_Level:: 9889* Attribute Lock_Free:: 9890* Attribute Loop_Entry:: 9891* Attribute Machine_Size:: 9892* Attribute Mantissa:: 9893* Attribute Maximum_Alignment:: 9894* Attribute Mechanism_Code:: 9895* Attribute Null_Parameter:: 9896* Attribute Object_Size:: 9897* Attribute Old:: 9898* Attribute Passed_By_Reference:: 9899* Attribute Pool_Address:: 9900* Attribute Range_Length:: 9901* Attribute Restriction_Set:: 9902* Attribute Result:: 9903* Attribute Safe_Emax:: 9904* Attribute Safe_Large:: 9905* Attribute Safe_Small:: 9906* Attribute Scalar_Storage_Order:: 9907* Attribute Simple_Storage_Pool:: 9908* Attribute Small:: 9909* Attribute Storage_Unit:: 9910* Attribute Stub_Type:: 9911* Attribute System_Allocator_Alignment:: 9912* Attribute Target_Name:: 9913* Attribute To_Address:: 9914* Attribute To_Any:: 9915* Attribute Type_Class:: 9916* Attribute Type_Key:: 9917* Attribute TypeCode:: 9918* Attribute Unconstrained_Array:: 9919* Attribute Universal_Literal_String:: 9920* Attribute Unrestricted_Access:: 9921* Attribute Update:: 9922* Attribute Valid_Scalars:: 9923* Attribute VADS_Size:: 9924* Attribute Value_Size:: 9925* Attribute Wchar_T_Size:: 9926* Attribute Word_Size:: 9927 9928@end menu 9929 9930@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 9931@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{161} 9932@section Attribute Abort_Signal 9933 9934 9935@geindex Abort_Signal 9936 9937@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 9938prefix) provides the entity for the special exception used to signal 9939task abort or asynchronous transfer of control. Normally this attribute 9940should only be used in the tasking runtime (it is highly peculiar, and 9941completely outside the normal semantics of Ada, for a user program to 9942intercept the abort exception). 9943 9944@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 9945@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{162} 9946@section Attribute Address_Size 9947 9948 9949@geindex Size of `@w{`}Address`@w{`} 9950 9951@geindex Address_Size 9952 9953@code{Standard'Address_Size} (@code{Standard} is the only allowed 9954prefix) is a static constant giving the number of bits in an 9955@code{Address}. It is the same value as System.Address'Size, 9956but has the advantage of being static, while a direct 9957reference to System.Address'Size is nonstatic because Address 9958is a private type. 9959 9960@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 9961@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{163} 9962@section Attribute Asm_Input 9963 9964 9965@geindex Asm_Input 9966 9967The @code{Asm_Input} attribute denotes a function that takes two 9968parameters. The first is a string, the second is an expression of the 9969type designated by the prefix. The first (string) argument is required 9970to be a static expression, and is the constraint for the parameter, 9971(e.g., what kind of register is required). The second argument is the 9972value to be used as the input argument. The possible values for the 9973constant are the same as those used in the RTL, and are dependent on 9974the configuration file used to built the GCC back end. 9975@ref{164,,Machine Code Insertions} 9976 9977@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 9978@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{165} 9979@section Attribute Asm_Output 9980 9981 9982@geindex Asm_Output 9983 9984The @code{Asm_Output} attribute denotes a function that takes two 9985parameters. The first is a string, the second is the name of a variable 9986of the type designated by the attribute prefix. The first (string) 9987argument is required to be a static expression and designates the 9988constraint for the parameter (e.g., what kind of register is 9989required). The second argument is the variable to be updated with the 9990result. The possible values for constraint are the same as those used in 9991the RTL, and are dependent on the configuration file used to build the 9992GCC back end. If there are no output operands, then this argument may 9993either be omitted, or explicitly given as @code{No_Output_Operands}. 9994@ref{164,,Machine Code Insertions} 9995 9996@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 9997@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{166} 9998@section Attribute Atomic_Always_Lock_Free 9999 10000 10001@geindex Atomic_Always_Lock_Free 10002 10003The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. 10004The result is a Boolean value which is True if the type has discriminants, 10005and False otherwise. The result indicate whether atomic operations are 10006supported by the target for the given type. 10007 10008@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 10009@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{167} 10010@section Attribute Bit 10011 10012 10013@geindex Bit 10014 10015@code{obj'Bit}, where @code{obj} is any object, yields the bit 10016offset within the storage unit (byte) that contains the first bit of 10017storage allocated for the object. The value of this attribute is of the 10018type @emph{universal_integer}, and is always a non-negative number not 10019exceeding the value of @code{System.Storage_Unit}. 10020 10021For an object that is a variable or a constant allocated in a register, 10022the value is zero. (The use of this attribute does not force the 10023allocation of a variable to memory). 10024 10025For an object that is a formal parameter, this attribute applies 10026to either the matching actual parameter or to a copy of the 10027matching actual parameter. 10028 10029For an access object the value is zero. Note that 10030@code{obj.all'Bit} is subject to an @code{Access_Check} for the 10031designated object. Similarly for a record component 10032@code{X.C'Bit} is subject to a discriminant check and 10033@code{X(I).Bit} and @code{X(I1..I2)'Bit} 10034are subject to index checks. 10035 10036This attribute is designed to be compatible with the DEC Ada 83 definition 10037and implementation of the @code{Bit} attribute. 10038 10039@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 10040@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{168} 10041@section Attribute Bit_Position 10042 10043 10044@geindex Bit_Position 10045 10046@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one 10047of the fields of the record type, yields the bit 10048offset within the record contains the first bit of 10049storage allocated for the object. The value of this attribute is of the 10050type @emph{universal_integer}. The value depends only on the field 10051@code{C} and is independent of the alignment of 10052the containing record @code{R}. 10053 10054@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 10055@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{169} 10056@section Attribute Code_Address 10057 10058 10059@geindex Code_Address 10060 10061@geindex Subprogram address 10062 10063@geindex Address of subprogram code 10064 10065The @code{'Address} 10066attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 10067intended effect seems to be to provide 10068an address value which can be used to call the subprogram by means of 10069an address clause as in the following example: 10070 10071@example 10072procedure K is ... 10073 10074procedure L; 10075for L'Address use K'Address; 10076pragma Import (Ada, L); 10077@end example 10078 10079A call to @code{L} is then expected to result in a call to @code{K}. 10080In Ada 83, where there were no access-to-subprogram values, this was 10081a common work-around for getting the effect of an indirect call. 10082GNAT implements the above use of @code{Address} and the technique 10083illustrated by the example code works correctly. 10084 10085However, for some purposes, it is useful to have the address of the start 10086of the generated code for the subprogram. On some architectures, this is 10087not necessarily the same as the @code{Address} value described above. 10088For example, the @code{Address} value may reference a subprogram 10089descriptor rather than the subprogram itself. 10090 10091The @code{'Code_Address} attribute, which can only be applied to 10092subprogram entities, always returns the address of the start of the 10093generated code of the specified subprogram, which may or may not be 10094the same value as is returned by the corresponding @code{'Address} 10095attribute. 10096 10097@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 10098@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16a} 10099@section Attribute Compiler_Version 10100 10101 10102@geindex Compiler_Version 10103 10104@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 10105prefix) yields a static string identifying the version of the compiler 10106being used to compile the unit containing the attribute reference. 10107 10108@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 10109@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16b} 10110@section Attribute Constrained 10111 10112 10113@geindex Constrained 10114 10115In addition to the usage of this attribute in the Ada RM, GNAT 10116also permits the use of the @code{'Constrained} attribute 10117in a generic template 10118for any type, including types without discriminants. The value of this 10119attribute in the generic instance when applied to a scalar type or a 10120record type without discriminants is always @code{True}. This usage is 10121compatible with older Ada compilers, including notably DEC Ada. 10122 10123@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 10124@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16c} 10125@section Attribute Default_Bit_Order 10126 10127 10128@geindex Big endian 10129 10130@geindex Little endian 10131 10132@geindex Default_Bit_Order 10133 10134@code{Standard'Default_Bit_Order} (@code{Standard} is the only 10135permissible prefix), provides the value @code{System.Default_Bit_Order} 10136as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 10137@code{Low_Order_First}). This is used to construct the definition of 10138@code{Default_Bit_Order} in package @code{System}. 10139 10140@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 10141@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{16d} 10142@section Attribute Default_Scalar_Storage_Order 10143 10144 10145@geindex Big endian 10146 10147@geindex Little endian 10148 10149@geindex Default_Scalar_Storage_Order 10150 10151@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only 10152permissible prefix), provides the current value of the default scalar storage 10153order (as specified using pragma @code{Default_Scalar_Storage_Order}, or 10154equal to @code{Default_Bit_Order} if unspecified) as a 10155@code{System.Bit_Order} value. This is a static attribute. 10156 10157@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 10158@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{16e} 10159@section Attribute Deref 10160 10161 10162@geindex Deref 10163 10164The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields 10165the variable of type @code{typ} that is located at the given address. It is similar 10166to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to 10167a named access-to-@cite{typ} type, except that it yields a variable, so it can be 10168used on the left side of an assignment. 10169 10170@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 10171@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{16f} 10172@section Attribute Descriptor_Size 10173 10174 10175@geindex Descriptor 10176 10177@geindex Dope vector 10178 10179@geindex Descriptor_Size 10180 10181Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the 10182descriptor allocated for a type. The result is non-zero only for unconstrained 10183array types and the returned value is of type universal integer. In GNAT, an 10184array descriptor contains bounds information and is located immediately before 10185the first element of the array. 10186 10187@example 10188type Unconstr_Array is array (Positive range <>) of Boolean; 10189Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 10190@end example 10191 10192The attribute takes into account any additional padding due to type alignment. 10193In the example above, the descriptor contains two values of type 10194@code{Positive} representing the low and high bound. Since @code{Positive} has 10195a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * Positive'Size + 2} or 64 bits. 10196 10197@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 10198@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{170} 10199@section Attribute Elaborated 10200 10201 10202@geindex Elaborated 10203 10204The prefix of the @code{'Elaborated} attribute must be a unit name. The 10205value is a Boolean which indicates whether or not the given unit has been 10206elaborated. This attribute is primarily intended for internal use by the 10207generated code for dynamic elaboration checking, but it can also be used 10208in user programs. The value will always be True once elaboration of all 10209units has been completed. An exception is for units which need no 10210elaboration, the value is always False for such units. 10211 10212@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 10213@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{171} 10214@section Attribute Elab_Body 10215 10216 10217@geindex Elab_Body 10218 10219This attribute can only be applied to a program unit name. It returns 10220the entity for the corresponding elaboration procedure for elaborating 10221the body of the referenced unit. This is used in the main generated 10222elaboration procedure by the binder and is not normally used in any 10223other context. However, there may be specialized situations in which it 10224is useful to be able to call this elaboration procedure from Ada code, 10225e.g., if it is necessary to do selective re-elaboration to fix some 10226error. 10227 10228@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 10229@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{172} 10230@section Attribute Elab_Spec 10231 10232 10233@geindex Elab_Spec 10234 10235This attribute can only be applied to a program unit name. It returns 10236the entity for the corresponding elaboration procedure for elaborating 10237the spec of the referenced unit. This is used in the main 10238generated elaboration procedure by the binder and is not normally used 10239in any other context. However, there may be specialized situations in 10240which it is useful to be able to call this elaboration procedure from 10241Ada code, e.g., if it is necessary to do selective re-elaboration to fix 10242some error. 10243 10244@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 10245@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{173} 10246@section Attribute Elab_Subp_Body 10247 10248 10249@geindex Elab_Subp_Body 10250 10251This attribute can only be applied to a library level subprogram 10252name and is only allowed in CodePeer mode. It returns the entity 10253for the corresponding elaboration procedure for elaborating the body 10254of the referenced subprogram unit. This is used in the main generated 10255elaboration procedure by the binder in CodePeer mode only and is unrecognized 10256otherwise. 10257 10258@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 10259@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{174} 10260@section Attribute Emax 10261 10262 10263@geindex Ada 83 attributes 10264 10265@geindex Emax 10266 10267The @code{Emax} attribute is provided for compatibility with Ada 83. See 10268the Ada 83 reference manual for an exact description of the semantics of 10269this attribute. 10270 10271@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 10272@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{175} 10273@section Attribute Enabled 10274 10275 10276@geindex Enabled 10277 10278The @code{Enabled} attribute allows an application program to check at compile 10279time to see if the designated check is currently enabled. The prefix is a 10280simple identifier, referencing any predefined check name (other than 10281@code{All_Checks}) or a check name introduced by pragma Check_Name. If 10282no argument is given for the attribute, the check is for the general state 10283of the check, if an argument is given, then it is an entity name, and the 10284check indicates whether an @code{Suppress} or @code{Unsuppress} has been 10285given naming the entity (if not, then the argument is ignored). 10286 10287Note that instantiations inherit the check status at the point of the 10288instantiation, so a useful idiom is to have a library package that 10289introduces a check name with @code{pragma Check_Name}, and then contains 10290generic packages or subprograms which use the @code{Enabled} attribute 10291to see if the check is enabled. A user of this package can then issue 10292a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 10293the package or subprogram, controlling whether the check will be present. 10294 10295@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 10296@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{176} 10297@section Attribute Enum_Rep 10298 10299 10300@geindex Representation of enums 10301 10302@geindex Enum_Rep 10303 10304For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a 10305function with the following spec: 10306 10307@example 10308function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 10309@end example 10310 10311It is also allowable to apply @code{Enum_Rep} directly to an object of an 10312enumeration type or to a non-overloaded enumeration 10313literal. In this case @code{S'Enum_Rep} is equivalent to 10314@code{typ'Enum_Rep(S)} where @code{typ} is the type of the 10315enumeration literal or object. 10316 10317The function returns the representation value for the given enumeration 10318value. This will be equal to value of the @code{Pos} attribute in the 10319absence of an enumeration representation clause. This is a static 10320attribute (i.e.,:the result is static if the argument is static). 10321 10322@code{S'Enum_Rep} can also be used with integer types and objects, 10323in which case it simply returns the integer value. The reason for this 10324is to allow it to be used for @code{(<>)} discrete formal arguments in 10325a generic unit that can be instantiated with either enumeration types 10326or integer types. Note that if @code{Enum_Rep} is used on a modular 10327type whose upper bound exceeds the upper bound of the largest signed 10328integer type, and the argument is a variable, so that the universal 10329integer calculation is done at run time, then the call to @code{Enum_Rep} 10330may raise @code{Constraint_Error}. 10331 10332@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 10333@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{177} 10334@section Attribute Enum_Val 10335 10336 10337@geindex Representation of enums 10338 10339@geindex Enum_Val 10340 10341For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a 10342function with the following spec: 10343 10344@example 10345function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 10346@end example 10347 10348The function returns the enumeration value whose representation matches the 10349argument, or raises Constraint_Error if no enumeration literal of the type 10350has the matching value. 10351This will be equal to value of the @code{Val} attribute in the 10352absence of an enumeration representation clause. This is a static 10353attribute (i.e., the result is static if the argument is static). 10354 10355@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 10356@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{178} 10357@section Attribute Epsilon 10358 10359 10360@geindex Ada 83 attributes 10361 10362@geindex Epsilon 10363 10364The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 10365the Ada 83 reference manual for an exact description of the semantics of 10366this attribute. 10367 10368@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes 10369@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{179} 10370@section Attribute Fast_Math 10371 10372 10373@geindex Fast_Math 10374 10375@code{Standard'Fast_Math} (@code{Standard} is the only allowed 10376prefix) yields a static Boolean value that is True if pragma 10377@code{Fast_Math} is active, and False otherwise. 10378 10379@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes 10380@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17a} 10381@section Attribute Finalization_Size 10382 10383 10384@geindex Finalization_Size 10385 10386The prefix of attribute @code{Finalization_Size} must be an object or 10387a non-class-wide type. This attribute returns the size of any hidden data 10388reserved by the compiler to handle finalization-related actions. The type of 10389the attribute is @emph{universal_integer}. 10390 10391@code{Finalization_Size} yields a value of zero for a type with no controlled 10392parts, an object whose type has no controlled parts, or an object of a 10393class-wide type whose tag denotes a type with no controlled parts. 10394 10395Note that only heap-allocated objects contain finalization data. 10396 10397@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes 10398@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17b} 10399@section Attribute Fixed_Value 10400 10401 10402@geindex Fixed_Value 10403 10404For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a 10405function with the following specification: 10406 10407@example 10408function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10409@end example 10410 10411The value returned is the fixed-point value @code{V} such that: 10412 10413@example 10414V = Arg * S'Small 10415@end example 10416 10417The effect is thus similar to first converting the argument to the 10418integer type used to represent @code{S}, and then doing an unchecked 10419conversion to the fixed-point type. The difference is 10420that there are full range checks, to ensure that the result is in range. 10421This attribute is primarily intended for use in implementation of the 10422input-output functions for fixed-point values. 10423 10424@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10425@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17c} 10426@section Attribute From_Any 10427 10428 10429@geindex From_Any 10430 10431This internal attribute is used for the generation of remote subprogram 10432stubs in the context of the Distributed Systems Annex. 10433 10434@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10435@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{17d} 10436@section Attribute Has_Access_Values 10437 10438 10439@geindex Access values 10440@geindex testing for 10441 10442@geindex Has_Access_Values 10443 10444The prefix of the @code{Has_Access_Values} attribute is a type. The result 10445is a Boolean value which is True if the is an access type, or is a composite 10446type with a component (at any nesting depth) that is an access type, and is 10447False otherwise. 10448The intended use of this attribute is in conjunction with generic 10449definitions. If the attribute is applied to a generic private type, it 10450indicates whether or not the corresponding actual type has access values. 10451 10452@node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes 10453@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{17e} 10454@section Attribute Has_Discriminants 10455 10456 10457@geindex Discriminants 10458@geindex testing for 10459 10460@geindex Has_Discriminants 10461 10462The prefix of the @code{Has_Discriminants} attribute is a type. The result 10463is a Boolean value which is True if the type has discriminants, and False 10464otherwise. The intended use of this attribute is in conjunction with generic 10465definitions. If the attribute is applied to a generic private type, it 10466indicates whether or not the corresponding actual type has discriminants. 10467 10468@node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes 10469@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{17f} 10470@section Attribute Img 10471 10472 10473@geindex Img 10474 10475The @code{Img} attribute differs from @code{Image} in that it is applied 10476directly to an object, and yields the same result as 10477@code{Image} for the subtype of the object. This is convenient for 10478debugging: 10479 10480@example 10481Put_Line ("X = " & X'Img); 10482@end example 10483 10484has the same meaning as the more verbose: 10485 10486@example 10487Put_Line ("X = " & T'Image (X)); 10488@end example 10489 10490where @code{T} is the (sub)type of the object @code{X}. 10491 10492Note that technically, in analogy to @code{Image}, 10493@code{X'Img} returns a parameterless function 10494that returns the appropriate string when called. This means that 10495@code{X'Img} can be renamed as a function-returning-string, or used 10496in an instantiation as a function parameter. 10497 10498@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes 10499@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{180} 10500@section Attribute Integer_Value 10501 10502 10503@geindex Integer_Value 10504 10505For every integer type @code{S}, @code{S'Integer_Value} denotes a 10506function with the following spec: 10507 10508@example 10509function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10510@end example 10511 10512The value returned is the integer value @code{V}, such that: 10513 10514@example 10515Arg = V * T'Small 10516@end example 10517 10518where @code{T} is the type of @code{Arg}. 10519The effect is thus similar to first doing an unchecked conversion from 10520the fixed-point type to its corresponding implementation type, and then 10521converting the result to the target integer type. The difference is 10522that there are full range checks, to ensure that the result is in range. 10523This attribute is primarily intended for use in implementation of the 10524standard input-output functions for fixed-point values. 10525 10526@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10527@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{181} 10528@section Attribute Invalid_Value 10529 10530 10531@geindex Invalid_Value 10532 10533For every scalar type S, S'Invalid_Value returns an undefined value of the 10534type. If possible this value is an invalid representation for the type. The 10535value returned is identical to the value used to initialize an otherwise 10536uninitialized value of the type if pragma Initialize_Scalars is used, 10537including the ability to modify the value with the binder -Sxx flag and 10538relevant environment variables at run time. 10539 10540@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10541@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{182} 10542@section Attribute Iterable 10543 10544 10545@geindex Iterable 10546 10547Equivalent to Aspect Iterable. 10548 10549@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10550@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{183} 10551@section Attribute Large 10552 10553 10554@geindex Ada 83 attributes 10555 10556@geindex Large 10557 10558The @code{Large} attribute is provided for compatibility with Ada 83. See 10559the Ada 83 reference manual for an exact description of the semantics of 10560this attribute. 10561 10562@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10563@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{184} 10564@section Attribute Library_Level 10565 10566 10567@geindex Library_Level 10568 10569@code{P'Library_Level}, where P is an entity name, 10570returns a Boolean value which is True if the entity is declared 10571at the library level, and False otherwise. Note that within a 10572generic instantition, the name of the generic unit denotes the 10573instance, which means that this attribute can be used to test 10574if a generic is instantiated at the library level, as shown 10575in this example: 10576 10577@example 10578generic 10579 ... 10580package Gen is 10581 pragma Compile_Time_Error 10582 (not Gen'Library_Level, 10583 "Gen can only be instantiated at library level"); 10584 ... 10585end Gen; 10586@end example 10587 10588@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10589@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{185} 10590@section Attribute Lock_Free 10591 10592 10593@geindex Lock_Free 10594 10595@code{P'Lock_Free}, where P is a protected object, returns True if a 10596pragma @code{Lock_Free} applies to P. 10597 10598@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 10599@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{186} 10600@section Attribute Loop_Entry 10601 10602 10603@geindex Loop_Entry 10604 10605Syntax: 10606 10607@example 10608X'Loop_Entry [(loop_name)] 10609@end example 10610 10611The @code{Loop_Entry} attribute is used to refer to the value that an 10612expression had upon entry to a given loop in much the same way that the 10613@code{Old} attribute in a subprogram postcondition can be used to refer 10614to the value an expression had upon entry to the subprogram. The 10615relevant loop is either identified by the given loop name, or it is the 10616innermost enclosing loop when no loop name is given. 10617 10618A @code{Loop_Entry} attribute can only occur within a 10619@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 10620@code{Loop_Entry} is to compare the current value of objects with their 10621initial value at loop entry, in a @code{Loop_Invariant} pragma. 10622 10623The effect of using @code{X'Loop_Entry} is the same as declaring 10624a constant initialized with the initial value of @code{X} at loop 10625entry. This copy is not performed if the loop is not entered, or if the 10626corresponding pragmas are ignored or disabled. 10627 10628@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 10629@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{187} 10630@section Attribute Machine_Size 10631 10632 10633@geindex Machine_Size 10634 10635This attribute is identical to the @code{Object_Size} attribute. It is 10636provided for compatibility with the DEC Ada 83 attribute of this name. 10637 10638@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 10639@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{188} 10640@section Attribute Mantissa 10641 10642 10643@geindex Ada 83 attributes 10644 10645@geindex Mantissa 10646 10647The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 10648the Ada 83 reference manual for an exact description of the semantics of 10649this attribute. 10650 10651@node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes 10652@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{189}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18a} 10653@section Attribute Maximum_Alignment 10654 10655 10656@geindex Alignment 10657@geindex maximum 10658 10659@geindex Maximum_Alignment 10660 10661@code{Standard'Maximum_Alignment} (@code{Standard} is the only 10662permissible prefix) provides the maximum useful alignment value for the 10663target. This is a static value that can be used to specify the alignment 10664for an object, guaranteeing that it is properly aligned in all 10665cases. 10666 10667@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes 10668@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18b} 10669@section Attribute Mechanism_Code 10670 10671 10672@geindex Return values 10673@geindex passing mechanism 10674 10675@geindex Parameters 10676@geindex passing mechanism 10677 10678@geindex Mechanism_Code 10679 10680@code{func'Mechanism_Code} yields an integer code for the 10681mechanism used for the result of function @code{func}, and 10682@code{subprog'Mechanism_Code (n)} yields the mechanism 10683used for formal parameter number @emph{n} (a static integer value, with 1 10684meaning the first parameter) of subprogram @code{subprog}. The code returned is: 10685 10686 10687@table @asis 10688 10689@item @emph{1} 10690 10691by copy (value) 10692 10693@item @emph{2} 10694 10695by reference 10696@end table 10697 10698@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 10699@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{18c} 10700@section Attribute Null_Parameter 10701 10702 10703@geindex Zero address 10704@geindex passing 10705 10706@geindex Null_Parameter 10707 10708A reference @code{T'Null_Parameter} denotes an imaginary object of 10709type or subtype @code{T} allocated at machine address zero. The attribute 10710is allowed only as the default expression of a formal parameter, or as 10711an actual expression of a subprogram call. In either case, the 10712subprogram must be imported. 10713 10714The identity of the object is represented by the address zero in the 10715argument list, independent of the passing mechanism (explicit or 10716default). 10717 10718This capability is needed to specify that a zero address should be 10719passed for a record or other composite object passed by reference. 10720There is no way of indicating this without the @code{Null_Parameter} 10721attribute. 10722 10723@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 10724@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{13f}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{18d} 10725@section Attribute Object_Size 10726 10727 10728@geindex Size 10729@geindex used for objects 10730 10731@geindex Object_Size 10732 10733The size of an object is not necessarily the same as the size of the type 10734of an object. This is because by default object sizes are increased to be 10735a multiple of the alignment of the object. For example, 10736@code{Natural'Size} is 1073731, but by default objects of type @code{Natural} will have a size of 32 bits. 10738Similarly, a record containing an integer and a character: 10739 10740@example 10741type Rec is record 10742 I : Integer; 10743 C : Character; 10744end record; 10745@end example 10746 10747will have a size of 40 (that is @code{Rec'Size} will be 40). The 10748alignment will be 4, because of the 10749integer field, and so the default size of record objects for this type 10750will be 64 (8 bytes). 10751 10752If the alignment of the above record is specified to be 1, then the 10753object size will be 40 (5 bytes). This is true by default, and also 10754an object size of 40 can be explicitly specified in this case. 10755 10756A consequence of this capability is that different object sizes can be 10757given to subtypes that would otherwise be considered in Ada to be 10758statically matching. But it makes no sense to consider such subtypes 10759as statically matching. Consequently, GNAT adds a rule 10760to the static matching rules that requires object sizes to match. 10761Consider this example: 10762 10763@example 10764 1. procedure BadAVConvert is 10765 2. type R is new Integer; 10766 3. subtype R1 is R range 1 .. 10; 10767 4. subtype R2 is R range 1 .. 10; 10768 5. for R1'Object_Size use 8; 10769 6. for R2'Object_Size use 16; 10770 7. type R1P is access all R1; 10771 8. type R2P is access all R2; 10772 9. R1PV : R1P := new R1'(4); 1077310. R2PV : R2P; 1077411. begin 1077512. R2PV := R2P (R1PV); 10776 | 10777 >>> target designated subtype not compatible with 10778 type "R1" defined at line 3 10779 1078013. end; 10781@end example 10782 10783In the absence of lines 5 and 6, 10784types @code{R1} and @code{R2} statically match and 10785hence the conversion on line 12 is legal. But since lines 5 and 6 10786cause the object sizes to differ, GNAT considers that types 10787@code{R1} and @code{R2} are not statically matching, and line 12 10788generates the diagnostic shown above. 10789 10790Similar additional checks are performed in other contexts requiring 10791statically matching subtypes. 10792 10793@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 10794@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{18e} 10795@section Attribute Old 10796 10797 10798@geindex Old 10799 10800In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage 10801within @code{Post} aspect), GNAT also permits the use of this attribute 10802in implementation defined pragmas @code{Postcondition}, 10803@code{Contract_Cases} and @code{Test_Case}. Also usages of 10804@code{Old} which would be illegal according to the Ada 2012 RM 10805definition are allowed under control of 10806implementation defined pragma @code{Unevaluated_Use_Of_Old}. 10807 10808@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 10809@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{18f} 10810@section Attribute Passed_By_Reference 10811 10812 10813@geindex Parameters 10814@geindex when passed by reference 10815 10816@geindex Passed_By_Reference 10817 10818@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns 10819a value of type @code{Boolean} value that is @code{True} if the type is 10820normally passed by reference and @code{False} if the type is normally 10821passed by copy in calls. For scalar types, the result is always @code{False} 10822and is static. For non-scalar types, the result is nonstatic. 10823 10824@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 10825@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{190} 10826@section Attribute Pool_Address 10827 10828 10829@geindex Parameters 10830@geindex when passed by reference 10831 10832@geindex Pool_Address 10833 10834@code{X'Pool_Address} for any object @code{X} returns the address 10835of X within its storage pool. This is the same as 10836@code{X'Address}, except that for an unconstrained array whose 10837bounds are allocated just before the first component, 10838@code{X'Pool_Address} returns the address of those bounds, 10839whereas @code{X'Address} returns the address of the first 10840component. 10841 10842Here, we are interpreting 'storage pool' broadly to mean 10843@code{wherever the object is allocated}, which could be a 10844user-defined storage pool, 10845the global heap, on the stack, or in a static memory area. 10846For an object created by @code{new}, @code{Ptr.all'Pool_Address} is 10847what is passed to @code{Allocate} and returned from @code{Deallocate}. 10848 10849@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 10850@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{191} 10851@section Attribute Range_Length 10852 10853 10854@geindex Range_Length 10855 10856@code{typ'Range_Length} for any discrete type @cite{typ} yields 10857the number of values represented by the subtype (zero for a null 10858range). The result is static for static subtypes. @code{Range_Length} 10859applied to the index subtype of a one dimensional array always gives the 10860same result as @code{Length} applied to the array itself. 10861 10862@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 10863@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{192} 10864@section Attribute Restriction_Set 10865 10866 10867@geindex Restriction_Set 10868 10869@geindex Restrictions 10870 10871This attribute allows compile time testing of restrictions that 10872are currently in effect. It is primarily intended for specializing 10873code in the run-time based on restrictions that are active (e.g. 10874don't need to save fpt registers if restriction No_Floating_Point 10875is known to be in effect), but can be used anywhere. 10876 10877There are two forms: 10878 10879@example 10880System'Restriction_Set (partition_boolean_restriction_NAME) 10881System'Restriction_Set (No_Dependence => library_unit_NAME); 10882@end example 10883 10884In the case of the first form, the only restriction names 10885allowed are parameterless restrictions that are checked 10886for consistency at bind time. For a complete list see the 10887subtype @code{System.Rident.Partition_Boolean_Restrictions}. 10888 10889The result returned is True if the restriction is known to 10890be in effect, and False if the restriction is known not to 10891be in effect. An important guarantee is that the value of 10892a Restriction_Set attribute is known to be consistent throughout 10893all the code of a partition. 10894 10895This is trivially achieved if the entire partition is compiled 10896with a consistent set of restriction pragmas. However, the 10897compilation model does not require this. It is possible to 10898compile one set of units with one set of pragmas, and another 10899set of units with another set of pragmas. It is even possible 10900to compile a spec with one set of pragmas, and then WITH the 10901same spec with a different set of pragmas. Inconsistencies 10902in the actual use of the restriction are checked at bind time. 10903 10904In order to achieve the guarantee of consistency for the 10905Restriction_Set pragma, we consider that a use of the pragma 10906that yields False is equivalent to a violation of the 10907restriction. 10908 10909So for example if you write 10910 10911@example 10912if System'Restriction_Set (No_Floating_Point) then 10913 ... 10914else 10915 ... 10916end if; 10917@end example 10918 10919And the result is False, so that the else branch is executed, 10920you can assume that this restriction is not set for any unit 10921in the partition. This is checked by considering this use of 10922the restriction pragma to be a violation of the restriction 10923No_Floating_Point. This means that no other unit can attempt 10924to set this restriction (if some unit does attempt to set it, 10925the binder will refuse to bind the partition). 10926 10927Technical note: The restriction name and the unit name are 10928intepreted entirely syntactically, as in the corresponding 10929Restrictions pragma, they are not analyzed semantically, 10930so they do not have a type. 10931 10932@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 10933@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{193} 10934@section Attribute Result 10935 10936 10937@geindex Result 10938 10939@code{function'Result} can only be used with in a Postcondition pragma 10940for a function. The prefix must be the name of the corresponding function. This 10941is used to refer to the result of the function in the postcondition expression. 10942For a further discussion of the use of this attribute and examples of its use, 10943see the description of pragma Postcondition. 10944 10945@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 10946@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{194} 10947@section Attribute Safe_Emax 10948 10949 10950@geindex Ada 83 attributes 10951 10952@geindex Safe_Emax 10953 10954The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 10955the Ada 83 reference manual for an exact description of the semantics of 10956this attribute. 10957 10958@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 10959@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{195} 10960@section Attribute Safe_Large 10961 10962 10963@geindex Ada 83 attributes 10964 10965@geindex Safe_Large 10966 10967The @code{Safe_Large} 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 Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 10972@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{196} 10973@section Attribute Safe_Small 10974 10975 10976@geindex Ada 83 attributes 10977 10978@geindex Safe_Small 10979 10980The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See 10981the Ada 83 reference manual for an exact description of the semantics of 10982this attribute. 10983 10984@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 10985@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{197}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{14c} 10986@section Attribute Scalar_Storage_Order 10987 10988 10989@geindex Endianness 10990 10991@geindex Scalar storage order 10992 10993@geindex Scalar_Storage_Order 10994 10995For every array or record type @code{S}, the representation attribute 10996@code{Scalar_Storage_Order} denotes the order in which storage elements 10997that make up scalar components are ordered within S. The value given must 10998be a static expression of type System.Bit_Order. The following is an example 10999of the use of this feature: 11000 11001@example 11002-- Component type definitions 11003 11004subtype Yr_Type is Natural range 0 .. 127; 11005subtype Mo_Type is Natural range 1 .. 12; 11006subtype Da_Type is Natural range 1 .. 31; 11007 11008-- Record declaration 11009 11010type Date is record 11011 Years_Since_1980 : Yr_Type; 11012 Month : Mo_Type; 11013 Day_Of_Month : Da_Type; 11014end record; 11015 11016-- Record representation clause 11017 11018for Date use record 11019 Years_Since_1980 at 0 range 0 .. 6; 11020 Month at 0 range 7 .. 10; 11021 Day_Of_Month at 0 range 11 .. 15; 11022end record; 11023 11024-- Attribute definition clauses 11025 11026for Date'Bit_Order use System.High_Order_First; 11027for Date'Scalar_Storage_Order use System.High_Order_First; 11028-- If Scalar_Storage_Order is specified, it must be consistent with 11029-- Bit_Order, so it's best to always define the latter explicitly if 11030-- the former is used. 11031@end example 11032 11033Other properties are as for standard representation attribute @code{Bit_Order}, 11034as defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 11035 11036For a record type @code{T}, if @code{T'Scalar_Storage_Order} is 11037specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 11038this means that if a @code{Scalar_Storage_Order} attribute definition 11039clause is not confirming, then the type's @code{Bit_Order} shall be 11040specified explicitly and set to the same value. 11041 11042Derived types inherit an explicitly set scalar storage order from their parent 11043types. This may be overridden for the derived type by giving an explicit scalar 11044storage order for the derived type. For a record extension, the derived type 11045must have the same scalar storage order as the parent type. 11046 11047A component of a record type that is itself a record or an array and that does 11048not start and end on a byte boundary must have have the same scalar storage 11049order as the record type. A component of a bit-packed array type that is itself 11050a record or an array must have the same scalar storage order as the array type. 11051 11052No component of a type that has an explicit @code{Scalar_Storage_Order} 11053attribute definition may be aliased. 11054 11055A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 11056with a value equal to @code{System.Default_Bit_Order}) has no effect. 11057 11058If the opposite storage order is specified, then whenever the value of 11059a scalar component of an object of type @code{S} is read, the storage 11060elements of the enclosing machine scalar are first reversed (before 11061retrieving the component value, possibly applying some shift and mask 11062operatings on the enclosing machine scalar), and the opposite operation 11063is done for writes. 11064 11065In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 11066are relaxed. Instead, the following rules apply: 11067 11068 11069@itemize * 11070 11071@item 11072the underlying storage elements are those at positions 11073@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 11074 11075@item 11076the sequence of underlying storage elements shall have 11077a size no greater than the largest machine scalar 11078 11079@item 11080the enclosing machine scalar is defined as the smallest machine 11081scalar starting at a position no greater than 11082@code{position + first_bit / storage_element_size} and covering 11083storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} 11084 11085@item 11086the position of the component is interpreted relative to that machine 11087scalar. 11088@end itemize 11089 11090If no scalar storage order is specified for a type (either directly, or by 11091inheritance in the case of a derived type), then the default is normally 11092the native ordering of the target, but this default can be overridden using 11093pragma @code{Default_Scalar_Storage_Order}. 11094 11095Note that if a component of @code{T} is itself of a record or array type, 11096the specfied @code{Scalar_Storage_Order} does @emph{not} apply to that nested type: 11097an explicit attribute definition clause must be provided for the component 11098type as well if desired. 11099 11100Note that the scalar storage order only affects the in-memory data 11101representation. It has no effect on the representation used by stream 11102attributes. 11103 11104@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 11105@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e3}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{198} 11106@section Attribute Simple_Storage_Pool 11107 11108 11109@geindex Storage pool 11110@geindex simple 11111 11112@geindex Simple storage pool 11113 11114@geindex Simple_Storage_Pool 11115 11116For every nonformal, nonderived access-to-object type @code{Acc}, the 11117representation attribute @code{Simple_Storage_Pool} may be specified 11118via an attribute_definition_clause (or by specifying the equivalent aspect): 11119 11120@example 11121My_Pool : My_Simple_Storage_Pool_Type; 11122 11123type Acc is access My_Data_Type; 11124 11125for Acc'Simple_Storage_Pool use My_Pool; 11126@end example 11127 11128The name given in an attribute_definition_clause for the 11129@code{Simple_Storage_Pool} attribute shall denote a variable of 11130a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}). 11131 11132The use of this attribute is only allowed for a prefix denoting a type 11133for which it has been specified. The type of the attribute is the type 11134of the variable specified as the simple storage pool of the access type, 11135and the attribute denotes that variable. 11136 11137It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 11138for the same access type. 11139 11140If the @code{Simple_Storage_Pool} attribute has been specified for an access 11141type, then applying the @code{Storage_Pool} attribute to the type is flagged 11142with a warning and its evaluation raises the exception @code{Program_Error}. 11143 11144If the Simple_Storage_Pool attribute has been specified for an access 11145type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} 11146returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 11147which is intended to indicate the number of storage elements reserved for 11148the simple storage pool. If the Storage_Size function has not been defined 11149for the simple storage pool type, then this attribute returns zero. 11150 11151If an access type @code{S} has a specified simple storage pool of type 11152@code{SSP}, then the evaluation of an allocator for that access type calls 11153the primitive @code{Allocate} procedure for type @code{SSP}, passing 11154@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 11155semantics of such allocators is the same as those defined for allocators 11156in section 13.11 of the @cite{Ada Reference Manual}, with the term 11157@emph{simple storage pool} substituted for @emph{storage pool}. 11158 11159If an access type @code{S} has a specified simple storage pool of type 11160@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 11161for that access type invokes the primitive @code{Deallocate} procedure 11162for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 11163parameter. The detailed semantics of such unchecked deallocations is the same 11164as defined in section 13.11.2 of the Ada Reference Manual, except that the 11165term @emph{simple storage pool} is substituted for @emph{storage pool}. 11166 11167@node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes 11168@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{199} 11169@section Attribute Small 11170 11171 11172@geindex Ada 83 attributes 11173 11174@geindex Small 11175 11176The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 11177fixed-point types. 11178GNAT also allows this attribute to be applied to floating-point types 11179for compatibility with Ada 83. See 11180the Ada 83 reference manual for an exact description of the semantics of 11181this attribute when applied to floating-point types. 11182 11183@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes 11184@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{19a} 11185@section Attribute Storage_Unit 11186 11187 11188@geindex Storage_Unit 11189 11190@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 11191prefix) provides the same value as @code{System.Storage_Unit}. 11192 11193@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 11194@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{19b} 11195@section Attribute Stub_Type 11196 11197 11198@geindex Stub_Type 11199 11200The GNAT implementation of remote access-to-classwide types is 11201organized as described in AARM section E.4 (20.t): a value of an RACW type 11202(designating a remote object) is represented as a normal access 11203value, pointing to a "stub" object which in turn contains the 11204necessary information to contact the designated remote object. A 11205call on any dispatching operation of such a stub object does the 11206remote call, if necessary, using the information in the stub object 11207to locate the target partition, etc. 11208 11209For a prefix @code{T} that denotes a remote access-to-classwide type, 11210@code{T'Stub_Type} denotes the type of the corresponding stub objects. 11211 11212By construction, the layout of @code{T'Stub_Type} is identical to that of 11213type @code{RACW_Stub_Type} declared in the internal implementation-defined 11214unit @code{System.Partition_Interface}. Use of this attribute will create 11215an implicit dependency on this unit. 11216 11217@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 11218@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{19c} 11219@section Attribute System_Allocator_Alignment 11220 11221 11222@geindex Alignment 11223@geindex allocator 11224 11225@geindex System_Allocator_Alignment 11226 11227@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 11228permissible prefix) provides the observable guaranted to be honored by 11229the system allocator (malloc). This is a static value that can be used 11230in user storage pools based on malloc either to reject allocation 11231with alignment too large or to enable a realignment circuitry if the 11232alignment request is larger than this value. 11233 11234@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 11235@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{19d} 11236@section Attribute Target_Name 11237 11238 11239@geindex Target_Name 11240 11241@code{Standard'Target_Name} (@code{Standard} is the only permissible 11242prefix) provides a static string value that identifies the target 11243for the current compilation. For GCC implementations, this is the 11244standard gcc target name without the terminating slash (for 11245example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 11246 11247@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 11248@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{19e} 11249@section Attribute To_Address 11250 11251 11252@geindex To_Address 11253 11254The @code{System'To_Address} 11255(@code{System} is the only permissible prefix) 11256denotes a function identical to 11257@code{System.Storage_Elements.To_Address} except that 11258it is a static attribute. This means that if its argument is 11259a static expression, then the result of the attribute is a 11260static expression. This means that such an expression can be 11261used in contexts (e.g., preelaborable packages) which require a 11262static expression and where the function call could not be used 11263(since the function call is always nonstatic, even if its 11264argument is static). The argument must be in the range 11265-(2**(m-1)) .. 2**m-1, where m is the memory size 11266(typically 32 or 64). Negative values are intepreted in a 11267modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 11268a 32 bits machine). 11269 11270@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 11271@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{19f} 11272@section Attribute To_Any 11273 11274 11275@geindex To_Any 11276 11277This internal attribute is used for the generation of remote subprogram 11278stubs in the context of the Distributed Systems Annex. 11279 11280@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 11281@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a0} 11282@section Attribute Type_Class 11283 11284 11285@geindex Type_Class 11286 11287@code{typ'Type_Class} for any type or subtype @cite{typ} yields 11288the value of the type class for the full type of @cite{typ}. If 11289@cite{typ} is a generic formal type, the value is the value for the 11290corresponding actual subtype. The value of this attribute is of type 11291@code{System.Aux_DEC.Type_Class}, which has the following definition: 11292 11293@example 11294type Type_Class is 11295 (Type_Class_Enumeration, 11296 Type_Class_Integer, 11297 Type_Class_Fixed_Point, 11298 Type_Class_Floating_Point, 11299 Type_Class_Array, 11300 Type_Class_Record, 11301 Type_Class_Access, 11302 Type_Class_Task, 11303 Type_Class_Address); 11304@end example 11305 11306Protected types yield the value @code{Type_Class_Task}, which thus 11307applies to all concurrent types. This attribute is designed to 11308be compatible with the DEC Ada 83 attribute of the same name. 11309 11310@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 11311@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a1} 11312@section Attribute Type_Key 11313 11314 11315@geindex Type_Key 11316 11317The @code{Type_Key} attribute is applicable to a type or subtype and 11318yields a value of type Standard.String containing encoded information 11319about the type or subtype. This provides improved compatibility with 11320other implementations that support this attribute. 11321 11322@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 11323@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1a2} 11324@section Attribute TypeCode 11325 11326 11327@geindex TypeCode 11328 11329This internal attribute is used for the generation of remote subprogram 11330stubs in the context of the Distributed Systems Annex. 11331 11332@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 11333@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1a3} 11334@section Attribute Unconstrained_Array 11335 11336 11337@geindex Unconstrained_Array 11338 11339The @code{Unconstrained_Array} attribute can be used with a prefix that 11340denotes any type or subtype. It is a static attribute that yields 11341@code{True} if the prefix designates an unconstrained array, 11342and @code{False} otherwise. In a generic instance, the result is 11343still static, and yields the result of applying this test to the 11344generic actual. 11345 11346@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 11347@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1a4} 11348@section Attribute Universal_Literal_String 11349 11350 11351@geindex Named numbers 11352@geindex representation of 11353 11354@geindex Universal_Literal_String 11355 11356The prefix of @code{Universal_Literal_String} must be a named 11357number. The static result is the string consisting of the characters of 11358the number as defined in the original source. This allows the user 11359program to access the actual text of named numbers without intermediate 11360conversions and without the need to enclose the strings in quotes (which 11361would preclude their use as numbers). 11362 11363For example, the following program prints the first 50 digits of pi: 11364 11365@example 11366with Text_IO; use Text_IO; 11367with Ada.Numerics; 11368procedure Pi is 11369begin 11370 Put (Ada.Numerics.Pi'Universal_Literal_String); 11371end; 11372@end example 11373 11374@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 11375@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1a5} 11376@section Attribute Unrestricted_Access 11377 11378 11379@geindex Access 11380@geindex unrestricted 11381 11382@geindex Unrestricted_Access 11383 11384The @code{Unrestricted_Access} attribute is similar to @code{Access} 11385except that all accessibility and aliased view checks are omitted. This 11386is a user-beware attribute. 11387 11388For objects, it is similar to @code{Address}, for which it is a 11389desirable replacement where the value desired is an access type. 11390In other words, its effect is similar to first applying the 11391@code{Address} attribute and then doing an unchecked conversion to a 11392desired access type. 11393 11394For subprograms, @code{P'Unrestricted_Access} may be used where 11395@code{P'Access} would be illegal, to construct a value of a 11396less-nested named access type that designates a more-nested 11397subprogram. This value may be used in indirect calls, so long as the 11398more-nested subprogram still exists; once the subprogram containing it 11399has returned, such calls are erroneous. For example: 11400 11401@example 11402package body P is 11403 11404 type Less_Nested is not null access procedure; 11405 Global : Less_Nested; 11406 11407 procedure P1 is 11408 begin 11409 Global.all; 11410 end P1; 11411 11412 procedure P2 is 11413 Local_Var : Integer; 11414 11415 procedure More_Nested is 11416 begin 11417 ... Local_Var ... 11418 end More_Nested; 11419 begin 11420 Global := More_Nested'Unrestricted_Access; 11421 P1; 11422 end P2; 11423 11424end P; 11425@end example 11426 11427When P1 is called from P2, the call via Global is OK, but if P1 were 11428called after P2 returns, it would be an erroneous use of a dangling 11429pointer. 11430 11431For objects, it is possible to use @code{Unrestricted_Access} for any 11432type. However, if the result is of an access-to-unconstrained array 11433subtype, then the resulting pointer has the same scope as the context 11434of the attribute, and must not be returned to some enclosing scope. 11435For instance, if a function uses @code{Unrestricted_Access} to create 11436an access-to-unconstrained-array and returns that value to the caller, 11437the result will involve dangling pointers. In addition, it is only 11438valid to create pointers to unconstrained arrays using this attribute 11439if the pointer has the normal default 'fat' representation where a 11440pointer has two components, one points to the array and one points to 11441the bounds. If a size clause is used to force 'thin' representation 11442for a pointer to unconstrained where there is only space for a single 11443pointer, then the resulting pointer is not usable. 11444 11445In the simple case where a direct use of Unrestricted_Access attempts 11446to make a thin pointer for a non-aliased object, the compiler will 11447reject the use as illegal, as shown in the following example: 11448 11449@example 11450with System; use System; 11451procedure SliceUA2 is 11452 type A is access all String; 11453 for A'Size use Standard'Address_Size; 11454 11455 procedure P (Arg : A) is 11456 begin 11457 null; 11458 end P; 11459 11460 X : String := "hello world!"; 11461 X2 : aliased String := "hello world!"; 11462 11463 AV : A := X'Unrestricted_Access; -- ERROR 11464 | 11465>>> illegal use of Unrestricted_Access attribute 11466>>> attempt to generate thin pointer to unaliased object 11467 11468begin 11469 P (X'Unrestricted_Access); -- ERROR 11470 | 11471>>> illegal use of Unrestricted_Access attribute 11472>>> attempt to generate thin pointer to unaliased object 11473 11474 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11475 | 11476>>> illegal use of Unrestricted_Access attribute 11477>>> attempt to generate thin pointer to unaliased object 11478 11479 P (X2'Unrestricted_Access); -- OK 11480end; 11481@end example 11482 11483but other cases cannot be detected by the compiler, and are 11484considered to be erroneous. Consider the following example: 11485 11486@example 11487with System; use System; 11488with System; use System; 11489procedure SliceUA is 11490 type AF is access all String; 11491 11492 type A is access all String; 11493 for A'Size use Standard'Address_Size; 11494 11495 procedure P (Arg : A) is 11496 begin 11497 if Arg'Length /= 6 then 11498 raise Program_Error; 11499 end if; 11500 end P; 11501 11502 X : String := "hello world!"; 11503 Y : AF := X (7 .. 12)'Unrestricted_Access; 11504 11505begin 11506 P (A (Y)); 11507end; 11508@end example 11509 11510A normal unconstrained array value 11511or a constrained array object marked as aliased has the bounds in memory 11512just before the array, so a thin pointer can retrieve both the data and 11513the bounds. But in this case, the non-aliased object @code{X} does not have the 11514bounds before the string. If the size clause for type @code{A} 11515were not present, then the pointer 11516would be a fat pointer, where one component is a pointer to the bounds, 11517and all would be well. But with the size clause present, the conversion from 11518fat pointer to thin pointer in the call loses the bounds, and so this 11519is erroneous, and the program likely raises a @code{Program_Error} exception. 11520 11521In general, it is advisable to completely 11522avoid mixing the use of thin pointers and the use of 11523@code{Unrestricted_Access} where the designated type is an 11524unconstrained array. The use of thin pointers should be restricted to 11525cases of porting legacy code that implicitly assumes the size of pointers, 11526and such code should not in any case be using this attribute. 11527 11528Another erroneous situation arises if the attribute is 11529applied to a constant. The resulting pointer can be used to access the 11530constant, but the effect of trying to modify a constant in this manner 11531is not well-defined. Consider this example: 11532 11533@example 11534P : constant Integer := 4; 11535type R is access all Integer; 11536RV : R := P'Unrestricted_Access; 11537.. 11538RV.all := 3; 11539@end example 11540 11541Here we attempt to modify the constant P from 4 to 3, but the compiler may 11542or may not notice this attempt, and subsequent references to P may yield 11543either the value 3 or the value 4 or the assignment may blow up if the 11544compiler decides to put P in read-only memory. One particular case where 11545@code{Unrestricted_Access} can be used in this way is to modify the 11546value of an @code{in} parameter: 11547 11548@example 11549procedure K (S : in String) is 11550 type R is access all Character; 11551 RV : R := S (3)'Unrestricted_Access; 11552begin 11553 RV.all := 'a'; 11554end; 11555@end example 11556 11557In general this is a risky approach. It may appear to "work" but such uses of 11558@code{Unrestricted_Access} are potentially non-portable, even from one version 11559of GNAT to another, so are best avoided if possible. 11560 11561@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes 11562@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1a6} 11563@section Attribute Update 11564 11565 11566@geindex Update 11567 11568The @code{Update} attribute creates a copy of an array or record value 11569with one or more modified components. The syntax is: 11570 11571@example 11572PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 11573PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 11574PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 11575 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 11576 11577MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 11578INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 11579INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 11580@end example 11581 11582where @code{PREFIX} is the name of an array or record object, the 11583association list in parentheses does not contain an @code{others} 11584choice and the box symbol @code{<>} may not appear in any 11585expression. The effect is to yield a copy of the array or record value 11586which is unchanged apart from the components mentioned in the 11587association list, which are changed to the indicated value. The 11588original value of the array or record value is not affected. For 11589example: 11590 11591@example 11592type Arr is Array (1 .. 5) of Integer; 11593... 11594Avar1 : Arr := (1,2,3,4,5); 11595Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 11596@end example 11597 11598yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 11599begin unmodified. Similarly: 11600 11601@example 11602type Rec is A, B, C : Integer; 11603... 11604Rvar1 : Rec := (A => 1, B => 2, C => 3); 11605Rvar2 : Rec := Rvar1'Update (B => 20); 11606@end example 11607 11608yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 11609with @code{Rvar1} being unmodifed. 11610Note that the value of the attribute reference is computed 11611completely before it is used. This means that if you write: 11612 11613@example 11614Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 11615@end example 11616 11617then the value of @code{Avar1} is not modified if @code{Function_Call} 11618raises an exception, unlike the effect of a series of direct assignments 11619to elements of @code{Avar1}. In general this requires that 11620two extra complete copies of the object are required, which should be 11621kept in mind when considering efficiency. 11622 11623The @code{Update} attribute cannot be applied to prefixes of a limited 11624type, and cannot reference discriminants in the case of a record type. 11625The accessibility level of an Update attribute result object is defined 11626as for an aggregate. 11627 11628In the record case, no component can be mentioned more than once. In 11629the array case, two overlapping ranges can appear in the association list, 11630in which case the modifications are processed left to right. 11631 11632Multi-dimensional arrays can be modified, as shown by this example: 11633 11634@example 11635A : array (1 .. 10, 1 .. 10) of Integer; 11636.. 11637A := A'Update ((1, 2) => 20, (3, 4) => 30); 11638@end example 11639 11640which changes element (1,2) to 20 and (3,4) to 30. 11641 11642@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes 11643@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1a7} 11644@section Attribute Valid_Scalars 11645 11646 11647@geindex Valid_Scalars 11648 11649The @code{'Valid_Scalars} attribute is intended to make it easier to 11650check the validity of scalar subcomponents of composite objects. It 11651is defined for any prefix @code{X} that denotes an object. 11652The value of this attribute is of the predefined type Boolean. 11653@code{X'Valid_Scalars} yields True if and only if evaluation of 11654@code{P'Valid} yields True for every scalar part P of X or if X has 11655no scalar parts. It is not specified in what order the scalar parts 11656are checked, nor whether any more are checked after any one of them 11657is determined to be invalid. If the prefix @code{X} is of a class-wide 11658type @code{T'Class} (where @code{T} is the associated specific type), 11659or if the prefix @code{X} is of a specific tagged type @code{T}, then 11660only the scalar parts of components of @code{T} are traversed; in other 11661words, components of extensions of @code{T} are not traversed even if 11662@code{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can 11663be determined at compile time that the prefix of the attribute has no 11664scalar parts (e.g., if the prefix is of an access type, an interface type, 11665an undiscriminated task type, or an undiscriminated protected type). 11666 11667For scalar types, @code{Valid_Scalars} is equivalent to @code{Valid}. The use 11668of this attribute is not permitted for @code{Unchecked_Union} types for which 11669in general it is not possible to determine the values of the discriminants. 11670 11671Note: @code{Valid_Scalars} can generate a lot of code, especially in the case 11672of a large variant record. If the attribute is called in many places in the 11673same program applied to objects of the same type, it can reduce program size 11674to write a function with a single use of the attribute, and then call that 11675function from multiple places. 11676 11677@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 11678@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1a8} 11679@section Attribute VADS_Size 11680 11681 11682@geindex Size 11683@geindex VADS compatibility 11684 11685@geindex VADS_Size 11686 11687The @code{'VADS_Size} attribute is intended to make it easier to port 11688legacy code which relies on the semantics of @code{'Size} as implemented 11689by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 11690same semantic interpretation. In particular, @code{'VADS_Size} applied 11691to a predefined or other primitive type with no Size clause yields the 11692Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 11693typical machines). In addition @code{'VADS_Size} applied to an object 11694gives the result that would be obtained by applying the attribute to 11695the corresponding type. 11696 11697@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 11698@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1a9}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15b} 11699@section Attribute Value_Size 11700 11701 11702@geindex Size 11703@geindex setting for not-first subtype 11704 11705@geindex Value_Size 11706 11707@code{type'Value_Size} is the number of bits required to represent 11708a value of the given subtype. It is the same as @code{type'Size}, 11709but, unlike @code{Size}, may be set for non-first subtypes. 11710 11711@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 11712@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1aa} 11713@section Attribute Wchar_T_Size 11714 11715 11716@geindex Wchar_T_Size 11717 11718@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 11719prefix) provides the size in bits of the C @code{wchar_t} type 11720primarily for constructing the definition of this type in 11721package @code{Interfaces.C}. The result is a static constant. 11722 11723@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 11724@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1ab} 11725@section Attribute Word_Size 11726 11727 11728@geindex Word_Size 11729 11730@code{Standard'Word_Size} (@code{Standard} is the only permissible 11731prefix) provides the value @code{System.Word_Size}. The result is 11732a static constant. 11733 11734@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 11735@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{1ac}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1ad} 11736@chapter Standard and Implementation Defined Restrictions 11737 11738 11739All Ada Reference Manual-defined Restriction identifiers are implemented: 11740 11741 11742@itemize * 11743 11744@item 11745language-defined restrictions (see 13.12.1) 11746 11747@item 11748tasking restrictions (see D.7) 11749 11750@item 11751high integrity restrictions (see H.4) 11752@end itemize 11753 11754GNAT implements additional restriction identifiers. All restrictions, whether 11755language defined or GNAT-specific, are listed in the following. 11756 11757@menu 11758* Partition-Wide Restrictions:: 11759* Program Unit Level Restrictions:: 11760 11761@end menu 11762 11763@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 11764@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1ae}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1af} 11765@section Partition-Wide Restrictions 11766 11767 11768There are two separate lists of restriction identifiers. The first 11769set requires consistency throughout a partition (in other words, if the 11770restriction identifier is used for any compilation unit in the partition, 11771then all compilation units in the partition must obey the restriction). 11772 11773@menu 11774* Immediate_Reclamation:: 11775* Max_Asynchronous_Select_Nesting:: 11776* Max_Entry_Queue_Length:: 11777* Max_Protected_Entries:: 11778* Max_Select_Alternatives:: 11779* Max_Storage_At_Blocking:: 11780* Max_Task_Entries:: 11781* Max_Tasks:: 11782* No_Abort_Statements:: 11783* No_Access_Parameter_Allocators:: 11784* No_Access_Subprograms:: 11785* No_Allocators:: 11786* No_Anonymous_Allocators:: 11787* No_Asynchronous_Control:: 11788* No_Calendar:: 11789* No_Coextensions:: 11790* No_Default_Initialization:: 11791* No_Delay:: 11792* No_Dependence:: 11793* No_Direct_Boolean_Operators:: 11794* No_Dispatch:: 11795* No_Dispatching_Calls:: 11796* No_Dynamic_Attachment:: 11797* No_Dynamic_Priorities:: 11798* No_Entry_Calls_In_Elaboration_Code:: 11799* No_Enumeration_Maps:: 11800* No_Exception_Handlers:: 11801* No_Exception_Propagation:: 11802* No_Exception_Registration:: 11803* No_Exceptions:: 11804* No_Finalization:: 11805* No_Fixed_Point:: 11806* No_Floating_Point:: 11807* No_Implicit_Conditionals:: 11808* No_Implicit_Dynamic_Code:: 11809* No_Implicit_Heap_Allocations:: 11810* No_Implicit_Protected_Object_Allocations:: 11811* No_Implicit_Task_Allocations:: 11812* No_Initialize_Scalars:: 11813* No_IO:: 11814* No_Local_Allocators:: 11815* No_Local_Protected_Objects:: 11816* No_Local_Timing_Events:: 11817* No_Long_Long_Integers:: 11818* No_Multiple_Elaboration:: 11819* No_Nested_Finalization:: 11820* No_Protected_Type_Allocators:: 11821* No_Protected_Types:: 11822* No_Recursion:: 11823* No_Reentrancy:: 11824* No_Relative_Delay:: 11825* No_Requeue_Statements:: 11826* No_Secondary_Stack:: 11827* No_Select_Statements:: 11828* No_Specific_Termination_Handlers:: 11829* No_Specification_of_Aspect:: 11830* No_Standard_Allocators_After_Elaboration:: 11831* No_Standard_Storage_Pools:: 11832* No_Stream_Optimizations:: 11833* No_Streams:: 11834* No_Task_Allocators:: 11835* No_Task_At_Interrupt_Priority:: 11836* No_Task_Attributes_Package:: 11837* No_Task_Hierarchy:: 11838* No_Task_Termination:: 11839* No_Tasking:: 11840* No_Terminate_Alternatives:: 11841* No_Unchecked_Access:: 11842* No_Unchecked_Conversion:: 11843* No_Unchecked_Deallocation:: 11844* No_Use_Of_Entity:: 11845* Pure_Barriers:: 11846* Simple_Barriers:: 11847* Static_Priorities:: 11848* Static_Storage_Size:: 11849 11850@end menu 11851 11852@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 11853@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b0} 11854@subsection Immediate_Reclamation 11855 11856 11857@geindex Immediate_Reclamation 11858 11859[RM H.4] This restriction ensures that, except for storage occupied by 11860objects created by allocators and not deallocated via unchecked 11861deallocation, any storage reserved at run time for an object is 11862immediately reclaimed when the object no longer exists. 11863 11864@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 11865@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b1} 11866@subsection Max_Asynchronous_Select_Nesting 11867 11868 11869@geindex Max_Asynchronous_Select_Nesting 11870 11871[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 11872selects. Violations of this restriction with a value of zero are 11873detected at compile time. Violations of this restriction with values 11874other than zero cause Storage_Error to be raised. 11875 11876@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 11877@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1b2} 11878@subsection Max_Entry_Queue_Length 11879 11880 11881@geindex Max_Entry_Queue_Length 11882 11883[RM D.7] This restriction is a declaration that any protected entry compiled in 11884the scope of the restriction has at most the specified number of 11885tasks waiting on the entry at any one time, and so no queue is required. 11886Note that this restriction is checked at run time. Violation of this 11887restriction results in the raising of Program_Error exception at the point of 11888the call. 11889 11890@geindex Max_Entry_Queue_Depth 11891 11892The restriction @code{Max_Entry_Queue_Depth} is recognized as a 11893synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 11894compatibility purposes (and a warning will be generated for its use if 11895warnings on obsolescent features are activated). 11896 11897@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 11898@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1b3} 11899@subsection Max_Protected_Entries 11900 11901 11902@geindex Max_Protected_Entries 11903 11904[RM D.7] Specifies the maximum number of entries per protected type. The 11905bounds of every entry family of a protected unit shall be static, or shall be 11906defined by a discriminant of a subtype whose corresponding bound is static. 11907 11908@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 11909@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1b4} 11910@subsection Max_Select_Alternatives 11911 11912 11913@geindex Max_Select_Alternatives 11914 11915[RM D.7] Specifies the maximum number of alternatives in a selective accept. 11916 11917@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 11918@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1b5} 11919@subsection Max_Storage_At_Blocking 11920 11921 11922@geindex Max_Storage_At_Blocking 11923 11924[RM D.7] Specifies the maximum portion (in storage elements) of a task's 11925Storage_Size that can be retained by a blocked task. A violation of this 11926restriction causes Storage_Error to be raised. 11927 11928@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 11929@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1b6} 11930@subsection Max_Task_Entries 11931 11932 11933@geindex Max_Task_Entries 11934 11935[RM D.7] Specifies the maximum number of entries 11936per task. The bounds of every entry family 11937of a task unit shall be static, or shall be 11938defined by a discriminant of a subtype whose 11939corresponding bound is static. 11940 11941@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 11942@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1b7} 11943@subsection Max_Tasks 11944 11945 11946@geindex Max_Tasks 11947 11948[RM D.7] Specifies the maximum number of task that may be created, not 11949counting the creation of the environment task. Violations of this 11950restriction with a value of zero are detected at compile 11951time. Violations of this restriction with values other than zero cause 11952Storage_Error to be raised. 11953 11954@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 11955@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1b8} 11956@subsection No_Abort_Statements 11957 11958 11959@geindex No_Abort_Statements 11960 11961[RM D.7] There are no abort_statements, and there are 11962no calls to Task_Identification.Abort_Task. 11963 11964@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 11965@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1b9} 11966@subsection No_Access_Parameter_Allocators 11967 11968 11969@geindex No_Access_Parameter_Allocators 11970 11971[RM H.4] This restriction ensures at compile time that there are no 11972occurrences of an allocator as the actual parameter to an access 11973parameter. 11974 11975@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 11976@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1ba} 11977@subsection No_Access_Subprograms 11978 11979 11980@geindex No_Access_Subprograms 11981 11982[RM H.4] This restriction ensures at compile time that there are no 11983declarations of access-to-subprogram types. 11984 11985@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 11986@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1bb} 11987@subsection No_Allocators 11988 11989 11990@geindex No_Allocators 11991 11992[RM H.4] This restriction ensures at compile time that there are no 11993occurrences of an allocator. 11994 11995@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 11996@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1bc} 11997@subsection No_Anonymous_Allocators 11998 11999 12000@geindex No_Anonymous_Allocators 12001 12002[RM H.4] This restriction ensures at compile time that there are no 12003occurrences of an allocator of anonymous access type. 12004 12005@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 12006@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1bd} 12007@subsection No_Asynchronous_Control 12008 12009 12010@geindex No_Asynchronous_Control 12011 12012[RM J.13] This restriction ensures at compile time that there are no semantic 12013dependences on the predefined package Asynchronous_Task_Control. 12014 12015@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 12016@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1be} 12017@subsection No_Calendar 12018 12019 12020@geindex No_Calendar 12021 12022[GNAT] This restriction ensures at compile time that there are no semantic 12023dependences on package Calendar. 12024 12025@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 12026@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1bf} 12027@subsection No_Coextensions 12028 12029 12030@geindex No_Coextensions 12031 12032[RM H.4] This restriction ensures at compile time that there are no 12033coextensions. See 3.10.2. 12034 12035@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 12036@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c0} 12037@subsection No_Default_Initialization 12038 12039 12040@geindex No_Default_Initialization 12041 12042[GNAT] This restriction prohibits any instance of default initialization 12043of variables. The binder implements a consistency rule which prevents 12044any unit compiled without the restriction from with'ing a unit with the 12045restriction (this allows the generation of initialization procedures to 12046be skipped, since you can be sure that no call is ever generated to an 12047initialization procedure in a unit with the restriction active). If used 12048in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 12049is to prohibit all cases of variables declared without a specific 12050initializer (including the case of OUT scalar parameters). 12051 12052@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 12053@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c1} 12054@subsection No_Delay 12055 12056 12057@geindex No_Delay 12058 12059[RM H.4] This restriction ensures at compile time that there are no 12060delay statements and no semantic dependences on package Calendar. 12061 12062@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 12063@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1c2} 12064@subsection No_Dependence 12065 12066 12067@geindex No_Dependence 12068 12069[RM 13.12.1] This restriction ensures at compile time that there are no 12070dependences on a library unit. 12071 12072@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 12073@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1c3} 12074@subsection No_Direct_Boolean_Operators 12075 12076 12077@geindex No_Direct_Boolean_Operators 12078 12079[GNAT] This restriction ensures that no logical operators (and/or/xor) 12080are used on operands of type Boolean (or any type derived from Boolean). 12081This is intended for use in safety critical programs where the certification 12082protocol requires the use of short-circuit (and then, or else) forms for all 12083composite boolean operations. 12084 12085@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 12086@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1c4} 12087@subsection No_Dispatch 12088 12089 12090@geindex No_Dispatch 12091 12092[RM H.4] This restriction ensures at compile time that there are no 12093occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 12094 12095@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 12096@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1c5} 12097@subsection No_Dispatching_Calls 12098 12099 12100@geindex No_Dispatching_Calls 12101 12102[GNAT] This restriction ensures at compile time that the code generated by the 12103compiler involves no dispatching calls. The use of this restriction allows the 12104safe use of record extensions, classwide membership tests and other classwide 12105features not involving implicit dispatching. This restriction ensures that 12106the code contains no indirect calls through a dispatching mechanism. Note that 12107this includes internally-generated calls created by the compiler, for example 12108in the implementation of class-wide objects assignments. The 12109membership test is allowed in the presence of this restriction, because its 12110implementation requires no dispatching. 12111This restriction is comparable to the official Ada restriction 12112@code{No_Dispatch} except that it is a bit less restrictive in that it allows 12113all classwide constructs that do not imply dispatching. 12114The following example indicates constructs that violate this restriction. 12115 12116@example 12117package Pkg is 12118 type T is tagged record 12119 Data : Natural; 12120 end record; 12121 procedure P (X : T); 12122 12123 type DT is new T with record 12124 More_Data : Natural; 12125 end record; 12126 procedure Q (X : DT); 12127end Pkg; 12128 12129with Pkg; use Pkg; 12130procedure Example is 12131 procedure Test (O : T'Class) is 12132 N : Natural := O'Size;-- Error: Dispatching call 12133 C : T'Class := O; -- Error: implicit Dispatching Call 12134 begin 12135 if O in DT'Class then -- OK : Membership test 12136 Q (DT (O)); -- OK : Type conversion plus direct call 12137 else 12138 P (O); -- Error: Dispatching call 12139 end if; 12140 end Test; 12141 12142 Obj : DT; 12143begin 12144 P (Obj); -- OK : Direct call 12145 P (T (Obj)); -- OK : Type conversion plus direct call 12146 P (T'Class (Obj)); -- Error: Dispatching call 12147 12148 Test (Obj); -- OK : Type conversion 12149 12150 if Obj in T'Class then -- OK : Membership test 12151 null; 12152 end if; 12153end Example; 12154@end example 12155 12156@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 12157@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1c6} 12158@subsection No_Dynamic_Attachment 12159 12160 12161@geindex No_Dynamic_Attachment 12162 12163[RM D.7] This restriction ensures that there is no call to any of the 12164operations defined in package Ada.Interrupts 12165(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 12166Detach_Handler, and Reference). 12167 12168@geindex No_Dynamic_Interrupts 12169 12170The restriction @code{No_Dynamic_Interrupts} is recognized as a 12171synonym for @code{No_Dynamic_Attachment}. This is retained for historical 12172compatibility purposes (and a warning will be generated for its use if 12173warnings on obsolescent features are activated). 12174 12175@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 12176@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1c7} 12177@subsection No_Dynamic_Priorities 12178 12179 12180@geindex No_Dynamic_Priorities 12181 12182[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 12183 12184@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 12185@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1c8} 12186@subsection No_Entry_Calls_In_Elaboration_Code 12187 12188 12189@geindex No_Entry_Calls_In_Elaboration_Code 12190 12191[GNAT] This restriction ensures at compile time that no task or protected entry 12192calls are made during elaboration code. As a result of the use of this 12193restriction, the compiler can assume that no code past an accept statement 12194in a task can be executed at elaboration time. 12195 12196@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 12197@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1c9} 12198@subsection No_Enumeration_Maps 12199 12200 12201@geindex No_Enumeration_Maps 12202 12203[GNAT] This restriction ensures at compile time that no operations requiring 12204enumeration maps are used (that is Image and Value attributes applied 12205to enumeration types). 12206 12207@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 12208@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1ca} 12209@subsection No_Exception_Handlers 12210 12211 12212@geindex No_Exception_Handlers 12213 12214[GNAT] This restriction ensures at compile time that there are no explicit 12215exception handlers. It also indicates that no exception propagation will 12216be provided. In this mode, exceptions may be raised but will result in 12217an immediate call to the last chance handler, a routine that the user 12218must define with the following profile: 12219 12220@example 12221procedure Last_Chance_Handler 12222 (Source_Location : System.Address; Line : Integer); 12223pragma Export (C, Last_Chance_Handler, 12224 "__gnat_last_chance_handler"); 12225@end example 12226 12227The parameter is a C null-terminated string representing a message to be 12228associated with the exception (typically the source location of the raise 12229statement generated by the compiler). The Line parameter when nonzero 12230represents the line number in the source program where the raise occurs. 12231 12232@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 12233@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1cb} 12234@subsection No_Exception_Propagation 12235 12236 12237@geindex No_Exception_Propagation 12238 12239[GNAT] This restriction guarantees that exceptions are never propagated 12240to an outer subprogram scope. The only case in which an exception may 12241be raised is when the handler is statically in the same subprogram, so 12242that the effect of a raise is essentially like a goto statement. Any 12243other raise statement (implicit or explicit) will be considered 12244unhandled. Exception handlers are allowed, but may not contain an 12245exception occurrence identifier (exception choice). In addition, use of 12246the package GNAT.Current_Exception is not permitted, and reraise 12247statements (raise with no operand) are not permitted. 12248 12249@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 12250@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1cc} 12251@subsection No_Exception_Registration 12252 12253 12254@geindex No_Exception_Registration 12255 12256[GNAT] This restriction ensures at compile time that no stream operations for 12257types Exception_Id or Exception_Occurrence are used. This also makes it 12258impossible to pass exceptions to or from a partition with this restriction 12259in a distributed environment. If this restriction is active, the generated 12260code is simplified by omitting the otherwise-required global registration 12261of exceptions when they are declared. 12262 12263@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 12264@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1cd} 12265@subsection No_Exceptions 12266 12267 12268@geindex No_Exceptions 12269 12270[RM H.4] This restriction ensures at compile time that there are no 12271raise statements and no exception handlers. 12272 12273@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 12274@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1ce} 12275@subsection No_Finalization 12276 12277 12278@geindex No_Finalization 12279 12280[GNAT] This restriction disables the language features described in 12281chapter 7.6 of the Ada 2005 RM as well as all form of code generation 12282performed by the compiler to support these features. The following types 12283are no longer considered controlled when this restriction is in effect: 12284 12285 12286@itemize * 12287 12288@item 12289@code{Ada.Finalization.Controlled} 12290 12291@item 12292@code{Ada.Finalization.Limited_Controlled} 12293 12294@item 12295Derivations from @code{Controlled} or @code{Limited_Controlled} 12296 12297@item 12298Class-wide types 12299 12300@item 12301Protected types 12302 12303@item 12304Task types 12305 12306@item 12307Array and record types with controlled components 12308@end itemize 12309 12310The compiler no longer generates code to initialize, finalize or adjust an 12311object or a nested component, either declared on the stack or on the heap. The 12312deallocation of a controlled object no longer finalizes its contents. 12313 12314@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 12315@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1cf} 12316@subsection No_Fixed_Point 12317 12318 12319@geindex No_Fixed_Point 12320 12321[RM H.4] This restriction ensures at compile time that there are no 12322occurrences of fixed point types and operations. 12323 12324@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 12325@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d0} 12326@subsection No_Floating_Point 12327 12328 12329@geindex No_Floating_Point 12330 12331[RM H.4] This restriction ensures at compile time that there are no 12332occurrences of floating point types and operations. 12333 12334@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 12335@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d1} 12336@subsection No_Implicit_Conditionals 12337 12338 12339@geindex No_Implicit_Conditionals 12340 12341[GNAT] This restriction ensures that the generated code does not contain any 12342implicit conditionals, either by modifying the generated code where possible, 12343or by rejecting any construct that would otherwise generate an implicit 12344conditional. Note that this check does not include run time constraint 12345checks, which on some targets may generate implicit conditionals as 12346well. To control the latter, constraint checks can be suppressed in the 12347normal manner. Constructs generating implicit conditionals include comparisons 12348of composite objects and the Max/Min attributes. 12349 12350@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 12351@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1d2} 12352@subsection No_Implicit_Dynamic_Code 12353 12354 12355@geindex No_Implicit_Dynamic_Code 12356 12357@geindex trampoline 12358 12359[GNAT] This restriction prevents the compiler from building 'trampolines'. 12360This is a structure that is built on the stack and contains dynamic 12361code to be executed at run time. On some targets, a trampoline is 12362built for the following features: @code{Access}, 12363@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 12364nested task bodies; primitive operations of nested tagged types. 12365Trampolines do not work on machines that prevent execution of stack 12366data. For example, on windows systems, enabling DEP (data execution 12367protection) will cause trampolines to raise an exception. 12368Trampolines are also quite slow at run time. 12369 12370On many targets, trampolines have been largely eliminated. Look at the 12371version of system.ads for your target --- if it has 12372Always_Compatible_Rep equal to False, then trampolines are largely 12373eliminated. In particular, a trampoline is built for the following 12374features: @code{Address} of a nested subprogram; 12375@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 12376but only if pragma Favor_Top_Level applies, or the access type has a 12377foreign-language convention; primitive operations of nested tagged 12378types. 12379 12380@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 12381@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1d3} 12382@subsection No_Implicit_Heap_Allocations 12383 12384 12385@geindex No_Implicit_Heap_Allocations 12386 12387[RM D.7] No constructs are allowed to cause implicit heap allocation. 12388 12389@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12390@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1d4} 12391@subsection No_Implicit_Protected_Object_Allocations 12392 12393 12394@geindex No_Implicit_Protected_Object_Allocations 12395 12396[GNAT] No constructs are allowed to cause implicit heap allocation of a 12397protected object. 12398 12399@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12400@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1d5} 12401@subsection No_Implicit_Task_Allocations 12402 12403 12404@geindex No_Implicit_Task_Allocations 12405 12406[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12407 12408@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12409@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1d6} 12410@subsection No_Initialize_Scalars 12411 12412 12413@geindex No_Initialize_Scalars 12414 12415[GNAT] This restriction ensures that no unit in the partition is compiled with 12416pragma Initialize_Scalars. This allows the generation of more efficient 12417code, and in particular eliminates dummy null initialization routines that 12418are otherwise generated for some record and array types. 12419 12420@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12421@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1d7} 12422@subsection No_IO 12423 12424 12425@geindex No_IO 12426 12427[RM H.4] This restriction ensures at compile time that there are no 12428dependences on any of the library units Sequential_IO, Direct_IO, 12429Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12430 12431@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12432@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1d8} 12433@subsection No_Local_Allocators 12434 12435 12436@geindex No_Local_Allocators 12437 12438[RM H.4] This restriction ensures at compile time that there are no 12439occurrences of an allocator in subprograms, generic subprograms, tasks, 12440and entry bodies. 12441 12442@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12443@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1d9} 12444@subsection No_Local_Protected_Objects 12445 12446 12447@geindex No_Local_Protected_Objects 12448 12449[RM D.7] This restriction ensures at compile time that protected objects are 12450only declared at the library level. 12451 12452@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12453@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1da} 12454@subsection No_Local_Timing_Events 12455 12456 12457@geindex No_Local_Timing_Events 12458 12459[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 12460declared at the library level. 12461 12462@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12463@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1db} 12464@subsection No_Long_Long_Integers 12465 12466 12467@geindex No_Long_Long_Integers 12468 12469[GNAT] This partition-wide restriction forbids any explicit reference to 12470type Standard.Long_Long_Integer, and also forbids declaring range types whose 12471implicit base type is Long_Long_Integer, and modular types whose size exceeds 12472Long_Integer'Size. 12473 12474@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12475@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1dc} 12476@subsection No_Multiple_Elaboration 12477 12478 12479@geindex No_Multiple_Elaboration 12480 12481[GNAT] When this restriction is active, we are not requesting control-flow 12482preservation with -fpreserve-control-flow, and the static elaboration model is 12483used, the compiler is allowed to suppress the elaboration counter normally 12484associated with the unit, even if the unit has elaboration code. This counter 12485is typically used to check for access before elaboration and to control 12486multiple elaboration attempts. If the restriction is used, then the 12487situations in which multiple elaboration is possible, including non-Ada main 12488programs and Stand Alone libraries, are not permitted and will be diagnosed 12489by the binder. 12490 12491@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12492@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1dd} 12493@subsection No_Nested_Finalization 12494 12495 12496@geindex No_Nested_Finalization 12497 12498[RM D.7] All objects requiring finalization are declared at the library level. 12499 12500@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12501@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1de} 12502@subsection No_Protected_Type_Allocators 12503 12504 12505@geindex No_Protected_Type_Allocators 12506 12507[RM D.7] This restriction ensures at compile time that there are no allocator 12508expressions that attempt to allocate protected objects. 12509 12510@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 12511@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1df} 12512@subsection No_Protected_Types 12513 12514 12515@geindex No_Protected_Types 12516 12517[RM H.4] This restriction ensures at compile time that there are no 12518declarations of protected types or protected objects. 12519 12520@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 12521@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e0} 12522@subsection No_Recursion 12523 12524 12525@geindex No_Recursion 12526 12527[RM H.4] A program execution is erroneous if a subprogram is invoked as 12528part of its execution. 12529 12530@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 12531@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e1} 12532@subsection No_Reentrancy 12533 12534 12535@geindex No_Reentrancy 12536 12537[RM H.4] A program execution is erroneous if a subprogram is executed by 12538two tasks at the same time. 12539 12540@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 12541@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1e2} 12542@subsection No_Relative_Delay 12543 12544 12545@geindex No_Relative_Delay 12546 12547[RM D.7] This restriction ensures at compile time that there are no delay 12548relative statements and prevents expressions such as @code{delay 1.23;} from 12549appearing in source code. 12550 12551@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 12552@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1e3} 12553@subsection No_Requeue_Statements 12554 12555 12556@geindex No_Requeue_Statements 12557 12558[RM D.7] This restriction ensures at compile time that no requeue statements 12559are permitted and prevents keyword @code{requeue} from being used in source 12560code. 12561 12562@geindex No_Requeue 12563 12564The restriction @code{No_Requeue} is recognized as a 12565synonym for @code{No_Requeue_Statements}. This is retained for historical 12566compatibility purposes (and a warning will be generated for its use if 12567warnings on oNobsolescent features are activated). 12568 12569@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 12570@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1e4} 12571@subsection No_Secondary_Stack 12572 12573 12574@geindex No_Secondary_Stack 12575 12576[GNAT] This restriction ensures at compile time that the generated code 12577does not contain any reference to the secondary stack. The secondary 12578stack is used to implement functions returning unconstrained objects 12579(arrays or records) on some targets. Suppresses the allocation of 12580secondary stacks for tasks (excluding the environment task) at run time. 12581 12582@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 12583@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1e5} 12584@subsection No_Select_Statements 12585 12586 12587@geindex No_Select_Statements 12588 12589[RM D.7] This restriction ensures at compile time no select statements of any 12590kind are permitted, that is the keyword @code{select} may not appear. 12591 12592@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 12593@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1e6} 12594@subsection No_Specific_Termination_Handlers 12595 12596 12597@geindex No_Specific_Termination_Handlers 12598 12599[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 12600or to Ada.Task_Termination.Specific_Handler. 12601 12602@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 12603@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1e7} 12604@subsection No_Specification_of_Aspect 12605 12606 12607@geindex No_Specification_of_Aspect 12608 12609[RM 13.12.1] This restriction checks at compile time that no aspect 12610specification, attribute definition clause, or pragma is given for a 12611given aspect. 12612 12613@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 12614@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1e8} 12615@subsection No_Standard_Allocators_After_Elaboration 12616 12617 12618@geindex No_Standard_Allocators_After_Elaboration 12619 12620[RM D.7] Specifies that an allocator using a standard storage pool 12621should never be evaluated at run time after the elaboration of the 12622library items of the partition has completed. Otherwise, Storage_Error 12623is raised. 12624 12625@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 12626@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1e9} 12627@subsection No_Standard_Storage_Pools 12628 12629 12630@geindex No_Standard_Storage_Pools 12631 12632[GNAT] This restriction ensures at compile time that no access types 12633use the standard default storage pool. Any access type declared must 12634have an explicit Storage_Pool attribute defined specifying a 12635user-defined storage pool. 12636 12637@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 12638@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1ea} 12639@subsection No_Stream_Optimizations 12640 12641 12642@geindex No_Stream_Optimizations 12643 12644[GNAT] This restriction affects the performance of stream operations on types 12645@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 12646compiler uses block reads and writes when manipulating @code{String} objects 12647due to their supperior performance. When this restriction is in effect, the 12648compiler performs all IO operations on a per-character basis. 12649 12650@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 12651@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1eb} 12652@subsection No_Streams 12653 12654 12655@geindex No_Streams 12656 12657[GNAT] This restriction ensures at compile/bind time that there are no 12658stream objects created and no use of stream attributes. 12659This restriction does not forbid dependences on the package 12660@code{Ada.Streams}. So it is permissible to with 12661@code{Ada.Streams} (or another package that does so itself) 12662as long as no actual stream objects are created and no 12663stream attributes are used. 12664 12665Note that the use of restriction allows optimization of tagged types, 12666since they do not need to worry about dispatching stream operations. 12667To take maximum advantage of this space-saving optimization, any 12668unit declaring a tagged type should be compiled with the restriction, 12669though this is not required. 12670 12671@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 12672@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1ec} 12673@subsection No_Task_Allocators 12674 12675 12676@geindex No_Task_Allocators 12677 12678[RM D.7] There are no allocators for task types 12679or types containing task subcomponents. 12680 12681@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 12682@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1ed} 12683@subsection No_Task_At_Interrupt_Priority 12684 12685 12686@geindex No_Task_At_Interrupt_Priority 12687 12688[GNAT] This restriction ensures at compile time that there is no 12689Interrupt_Priority aspect or pragma for a task or a task type. As 12690a consequence, the tasks are always created with a priority below 12691that an interrupt priority. 12692 12693@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 12694@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1ee} 12695@subsection No_Task_Attributes_Package 12696 12697 12698@geindex No_Task_Attributes_Package 12699 12700[GNAT] This restriction ensures at compile time that there are no implicit or 12701explicit dependencies on the package @code{Ada.Task_Attributes}. 12702 12703@geindex No_Task_Attributes 12704 12705The restriction @code{No_Task_Attributes} is recognized as a synonym 12706for @code{No_Task_Attributes_Package}. This is retained for historical 12707compatibility purposes (and a warning will be generated for its use if 12708warnings on obsolescent features are activated). 12709 12710@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 12711@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1ef} 12712@subsection No_Task_Hierarchy 12713 12714 12715@geindex No_Task_Hierarchy 12716 12717[RM D.7] All (non-environment) tasks depend 12718directly on the environment task of the partition. 12719 12720@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 12721@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f0} 12722@subsection No_Task_Termination 12723 12724 12725@geindex No_Task_Termination 12726 12727[RM D.7] Tasks that terminate are erroneous. 12728 12729@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 12730@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1f1} 12731@subsection No_Tasking 12732 12733 12734@geindex No_Tasking 12735 12736[GNAT] This restriction prevents the declaration of tasks or task types 12737throughout the partition. It is similar in effect to the use of 12738@code{Max_Tasks => 0} except that violations are caught at compile time 12739and cause an error message to be output either by the compiler or 12740binder. 12741 12742@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 12743@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1f2} 12744@subsection No_Terminate_Alternatives 12745 12746 12747@geindex No_Terminate_Alternatives 12748 12749[RM D.7] There are no selective accepts with terminate alternatives. 12750 12751@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 12752@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1f3} 12753@subsection No_Unchecked_Access 12754 12755 12756@geindex No_Unchecked_Access 12757 12758[RM H.4] This restriction ensures at compile time that there are no 12759occurrences of the Unchecked_Access attribute. 12760 12761@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 12762@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1f4} 12763@subsection No_Unchecked_Conversion 12764 12765 12766@geindex No_Unchecked_Conversion 12767 12768[RM J.13] This restriction ensures at compile time that there are no semantic 12769dependences on the predefined generic function Unchecked_Conversion. 12770 12771@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 12772@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1f5} 12773@subsection No_Unchecked_Deallocation 12774 12775 12776@geindex No_Unchecked_Deallocation 12777 12778[RM J.13] This restriction ensures at compile time that there are no semantic 12779dependences on the predefined generic procedure Unchecked_Deallocation. 12780 12781@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 12782@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1f6} 12783@subsection No_Use_Of_Entity 12784 12785 12786@geindex No_Use_Of_Entity 12787 12788[GNAT] This restriction ensures at compile time that there are no references 12789to the entity given in the form 12790 12791@example 12792No_Use_Of_Entity => Name 12793@end example 12794 12795where @code{Name} is the fully qualified entity, for example 12796 12797@example 12798No_Use_Of_Entity => Ada.Text_IO.Put_Line 12799@end example 12800 12801@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 12802@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1f7} 12803@subsection Pure_Barriers 12804 12805 12806@geindex Pure_Barriers 12807 12808[GNAT] This restriction ensures at compile time that protected entry 12809barriers are restricted to: 12810 12811 12812@itemize * 12813 12814@item 12815components of the protected object (excluding selection from dereferences), 12816 12817@item 12818constant declarations, 12819 12820@item 12821named numbers, 12822 12823@item 12824enumeration literals, 12825 12826@item 12827integer literals, 12828 12829@item 12830real literals, 12831 12832@item 12833character literals, 12834 12835@item 12836implicitly defined comparison operators, 12837 12838@item 12839uses of the Standard."not" operator, 12840 12841@item 12842short-circuit operator, 12843 12844@item 12845the Count attribute 12846@end itemize 12847 12848This restriction is a relaxation of the Simple_Barriers restriction, 12849but still ensures absence of side effects, exceptions, and recursion 12850during the evaluation of the barriers. 12851 12852@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 12853@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{1f8} 12854@subsection Simple_Barriers 12855 12856 12857@geindex Simple_Barriers 12858 12859[RM D.7] This restriction ensures at compile time that barriers in entry 12860declarations for protected types are restricted to either static boolean 12861expressions or references to simple boolean variables defined in the private 12862part of the protected type. No other form of entry barriers is permitted. 12863 12864@geindex Boolean_Entry_Barriers 12865 12866The restriction @code{Boolean_Entry_Barriers} is recognized as a 12867synonym for @code{Simple_Barriers}. This is retained for historical 12868compatibility purposes (and a warning will be generated for its use if 12869warnings on obsolescent features are activated). 12870 12871@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 12872@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{1f9} 12873@subsection Static_Priorities 12874 12875 12876@geindex Static_Priorities 12877 12878[GNAT] This restriction ensures at compile time that all priority expressions 12879are static, and that there are no dependences on the package 12880@code{Ada.Dynamic_Priorities}. 12881 12882@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 12883@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{1fa} 12884@subsection Static_Storage_Size 12885 12886 12887@geindex Static_Storage_Size 12888 12889[GNAT] This restriction ensures at compile time that any expression appearing 12890in a Storage_Size pragma or attribute definition clause is static. 12891 12892@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 12893@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{1fb}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{1fc} 12894@section Program Unit Level Restrictions 12895 12896 12897The second set of restriction identifiers 12898does not require partition-wide consistency. 12899The restriction may be enforced for a single 12900compilation unit without any effect on any of the 12901other compilation units in the partition. 12902 12903@menu 12904* No_Elaboration_Code:: 12905* No_Dynamic_Sized_Objects:: 12906* No_Entry_Queue:: 12907* No_Implementation_Aspect_Specifications:: 12908* No_Implementation_Attributes:: 12909* No_Implementation_Identifiers:: 12910* No_Implementation_Pragmas:: 12911* No_Implementation_Restrictions:: 12912* No_Implementation_Units:: 12913* No_Implicit_Aliasing:: 12914* No_Implicit_Loops:: 12915* No_Obsolescent_Features:: 12916* No_Wide_Characters:: 12917* Static_Dispatch_Tables:: 12918* SPARK_05:: 12919 12920@end menu 12921 12922@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions 12923@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{1fd} 12924@subsection No_Elaboration_Code 12925 12926 12927@geindex No_Elaboration_Code 12928 12929[GNAT] This restriction ensures at compile time that no elaboration code is 12930generated. Note that this is not the same condition as is enforced 12931by pragma @code{Preelaborate}. There are cases in which pragma 12932@code{Preelaborate} still permits code to be generated (e.g., code 12933to initialize a large array to all zeroes), and there are cases of units 12934which do not meet the requirements for pragma @code{Preelaborate}, 12935but for which no elaboration code is generated. Generally, it is 12936the case that preelaborable units will meet the restrictions, with 12937the exception of large aggregates initialized with an others_clause, 12938and exception declarations (which generate calls to a run-time 12939registry procedure). This restriction is enforced on 12940a unit by unit basis, it need not be obeyed consistently 12941throughout a partition. 12942 12943In the case of aggregates with others, if the aggregate has a dynamic 12944size, there is no way to eliminate the elaboration code (such dynamic 12945bounds would be incompatible with @code{Preelaborate} in any case). If 12946the bounds are static, then use of this restriction actually modifies 12947the code choice of the compiler to avoid generating a loop, and instead 12948generate the aggregate statically if possible, no matter how many times 12949the data for the others clause must be repeatedly generated. 12950 12951It is not possible to precisely document 12952the constructs which are compatible with this restriction, since, 12953unlike most other restrictions, this is not a restriction on the 12954source code, but a restriction on the generated object code. For 12955example, if the source contains a declaration: 12956 12957@example 12958Val : constant Integer := X; 12959@end example 12960 12961where X is not a static constant, it may be possible, depending 12962on complex optimization circuitry, for the compiler to figure 12963out the value of X at compile time, in which case this initialization 12964can be done by the loader, and requires no initialization code. It 12965is not possible to document the precise conditions under which the 12966optimizer can figure this out. 12967 12968Note that this the implementation of this restriction requires full 12969code generation. If it is used in conjunction with "semantics only" 12970checking, then some cases of violations may be missed. 12971 12972When this restriction is active, we are not requesting control-flow 12973preservation with -fpreserve-control-flow, and the static elaboration model is 12974used, the compiler is allowed to suppress the elaboration counter normally 12975associated with the unit. This counter is typically used to check for access 12976before elaboration and to control multiple elaboration attempts. 12977 12978@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions 12979@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{1fe} 12980@subsection No_Dynamic_Sized_Objects 12981 12982 12983@geindex No_Dynamic_Sized_Objects 12984 12985[GNAT] This restriction disallows certain constructs that might lead to the 12986creation of dynamic-sized composite objects (or array or discriminated type). 12987An array subtype indication is illegal if the bounds are not static 12988or references to discriminants of an enclosing type. 12989A discriminated subtype indication is illegal if the type has 12990discriminant-dependent array components or a variant part, and the 12991discriminants are not static. In addition, array and record aggregates are 12992illegal in corresponding cases. Note that this restriction does not forbid 12993access discriminants. It is often a good idea to combine this restriction 12994with No_Secondary_Stack. 12995 12996@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 12997@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{1ff} 12998@subsection No_Entry_Queue 12999 13000 13001@geindex No_Entry_Queue 13002 13003[GNAT] This restriction is a declaration that any protected entry compiled in 13004the scope of the restriction has at most one task waiting on the entry 13005at any one time, and so no queue is required. This restriction is not 13006checked at compile time. A program execution is erroneous if an attempt 13007is made to queue a second task on such an entry. 13008 13009@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 13010@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{200} 13011@subsection No_Implementation_Aspect_Specifications 13012 13013 13014@geindex No_Implementation_Aspect_Specifications 13015 13016[RM 13.12.1] This restriction checks at compile time that no 13017GNAT-defined aspects are present. With this restriction, the only 13018aspects that can be used are those defined in the Ada Reference Manual. 13019 13020@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 13021@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{201} 13022@subsection No_Implementation_Attributes 13023 13024 13025@geindex No_Implementation_Attributes 13026 13027[RM 13.12.1] This restriction checks at compile time that no 13028GNAT-defined attributes are present. With this restriction, the only 13029attributes that can be used are those defined in the Ada Reference 13030Manual. 13031 13032@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 13033@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{202} 13034@subsection No_Implementation_Identifiers 13035 13036 13037@geindex No_Implementation_Identifiers 13038 13039[RM 13.12.1] This restriction checks at compile time that no 13040implementation-defined identifiers (marked with pragma Implementation_Defined) 13041occur within language-defined packages. 13042 13043@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 13044@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{203} 13045@subsection No_Implementation_Pragmas 13046 13047 13048@geindex No_Implementation_Pragmas 13049 13050[RM 13.12.1] This restriction checks at compile time that no 13051GNAT-defined pragmas are present. With this restriction, the only 13052pragmas that can be used are those defined in the Ada Reference Manual. 13053 13054@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 13055@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{204} 13056@subsection No_Implementation_Restrictions 13057 13058 13059@geindex No_Implementation_Restrictions 13060 13061[GNAT] This restriction checks at compile time that no GNAT-defined restriction 13062identifiers (other than @code{No_Implementation_Restrictions} itself) 13063are present. With this restriction, the only other restriction identifiers 13064that can be used are those defined in the Ada Reference Manual. 13065 13066@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 13067@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{205} 13068@subsection No_Implementation_Units 13069 13070 13071@geindex No_Implementation_Units 13072 13073[RM 13.12.1] This restriction checks at compile time that there is no 13074mention in the context clause of any implementation-defined descendants 13075of packages Ada, Interfaces, or System. 13076 13077@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions 13078@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{206} 13079@subsection No_Implicit_Aliasing 13080 13081 13082@geindex No_Implicit_Aliasing 13083 13084[GNAT] This restriction, which is not required to be partition-wide consistent, 13085requires an explicit aliased keyword for an object to which 'Access, 13086'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 13087the 'Unrestricted_Access attribute for objects. Note: the reason that 13088Unrestricted_Access is forbidden is that it would require the prefix 13089to be aliased, and in such cases, it can always be replaced by 13090the standard attribute Unchecked_Access which is preferable. 13091 13092@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions 13093@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{207} 13094@subsection No_Implicit_Loops 13095 13096 13097@geindex No_Implicit_Loops 13098 13099[GNAT] This restriction ensures that the generated code of the unit marked 13100with this restriction does not contain any implicit @code{for} loops, either by 13101modifying the generated code where possible, or by rejecting any construct 13102that would otherwise generate an implicit @code{for} loop. If this restriction is 13103active, it is possible to build large array aggregates with all static 13104components without generating an intermediate temporary, and without generating 13105a loop to initialize individual components. Otherwise, a loop is created for 13106arrays larger than about 5000 scalar components. Note that if this restriction 13107is set in the spec of a package, it will not apply to its body. 13108 13109@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions 13110@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{208} 13111@subsection No_Obsolescent_Features 13112 13113 13114@geindex No_Obsolescent_Features 13115 13116[RM 13.12.1] This restriction checks at compile time that no obsolescent 13117features are used, as defined in Annex J of the Ada Reference Manual. 13118 13119@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions 13120@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{209} 13121@subsection No_Wide_Characters 13122 13123 13124@geindex No_Wide_Characters 13125 13126[GNAT] This restriction ensures at compile time that no uses of the types 13127@code{Wide_Character} or @code{Wide_String} or corresponding wide 13128wide types 13129appear, and that no wide or wide wide string or character literals 13130appear in the program (that is literals representing characters not in 13131type @code{Character}). 13132 13133@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions 13134@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{20a} 13135@subsection Static_Dispatch_Tables 13136 13137 13138@geindex Static_Dispatch_Tables 13139 13140[GNAT] This restriction checks at compile time that all the artifacts 13141associated with dispatch tables can be placed in read-only memory. 13142 13143@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions 13144@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{20b} 13145@subsection SPARK_05 13146 13147 13148@geindex SPARK_05 13149 13150[GNAT] This restriction checks at compile time that some constructs forbidden 13151in SPARK 2005 are not present. Note that SPARK 2005 has been superseded by 13152SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that 13153a codebase respects SPARK 2014 restrictions, mark the code with pragma or 13154aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as 13155follows: 13156 13157@example 13158gnatprove -P project.gpr --mode=stone 13159@end example 13160 13161or equivalently: 13162 13163@example 13164gnatprove -P project.gpr --mode=check_all 13165@end example 13166 13167With restriction @code{SPARK_05}, error messages related to SPARK 2005 restriction 13168have the form: 13169 13170@example 13171violation of restriction "SPARK_05" at <source-location> 13172 <error message> 13173@end example 13174 13175@geindex SPARK 13176 13177The restriction @code{SPARK} is recognized as a synonym for @code{SPARK_05}. This is 13178retained for historical compatibility purposes (and an unconditional warning 13179will be generated for its use, advising replacement by @code{SPARK_05}). 13180 13181This is not a replacement for the semantic checks performed by the 13182SPARK Examiner tool, as the compiler currently only deals with code, 13183not SPARK 2005 annotations, and does not guarantee catching all 13184cases of constructs forbidden by SPARK 2005. 13185 13186Thus it may well be the case that code which passes the compiler with 13187the SPARK 2005 restriction is rejected by the SPARK Examiner, e.g. due to 13188the different visibility rules of the Examiner based on SPARK 2005 13189@code{inherit} annotations. 13190 13191This restriction can be useful in providing an initial filter for code 13192developed using SPARK 2005, or in examining legacy code to see how far 13193it is from meeting SPARK 2005 restrictions. 13194 13195The list below summarizes the checks that are performed when this 13196restriction is in force: 13197 13198 13199@itemize * 13200 13201@item 13202No block statements 13203 13204@item 13205No case statements with only an others clause 13206 13207@item 13208Exit statements in loops must respect the SPARK 2005 language restrictions 13209 13210@item 13211No goto statements 13212 13213@item 13214Return can only appear as last statement in function 13215 13216@item 13217Function must have return statement 13218 13219@item 13220Loop parameter specification must include subtype mark 13221 13222@item 13223Prefix of expanded name cannot be a loop statement 13224 13225@item 13226Abstract subprogram not allowed 13227 13228@item 13229User-defined operators not allowed 13230 13231@item 13232Access type parameters not allowed 13233 13234@item 13235Default expressions for parameters not allowed 13236 13237@item 13238Default expressions for record fields not allowed 13239 13240@item 13241No tasking constructs allowed 13242 13243@item 13244Label needed at end of subprograms and packages 13245 13246@item 13247No mixing of positional and named parameter association 13248 13249@item 13250No access types as result type 13251 13252@item 13253No unconstrained arrays as result types 13254 13255@item 13256No null procedures 13257 13258@item 13259Initial and later declarations must be in correct order (declaration can't come after body) 13260 13261@item 13262No attributes on private types if full declaration not visible 13263 13264@item 13265No package declaration within package specification 13266 13267@item 13268No controlled types 13269 13270@item 13271No discriminant types 13272 13273@item 13274No overloading 13275 13276@item 13277Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed) 13278 13279@item 13280Access attribute not allowed 13281 13282@item 13283Allocator not allowed 13284 13285@item 13286Result of catenation must be String 13287 13288@item 13289Operands of catenation must be string literal, static char or another catenation 13290 13291@item 13292No conditional expressions 13293 13294@item 13295No explicit dereference 13296 13297@item 13298Quantified expression not allowed 13299 13300@item 13301Slicing not allowed 13302 13303@item 13304No exception renaming 13305 13306@item 13307No generic renaming 13308 13309@item 13310No object renaming 13311 13312@item 13313No use clause 13314 13315@item 13316Aggregates must be qualified 13317 13318@item 13319Nonstatic choice in array aggregates not allowed 13320 13321@item 13322The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type 13323 13324@item 13325No mixing of positional and named association in aggregate, no multi choice 13326 13327@item 13328AND, OR and XOR for arrays only allowed when operands have same static bounds 13329 13330@item 13331Fixed point operands to * or / must be qualified or converted 13332 13333@item 13334Comparison operators not allowed for Booleans or arrays (except strings) 13335 13336@item 13337Equality not allowed for arrays with non-matching static bounds (except strings) 13338 13339@item 13340Conversion / qualification not allowed for arrays with non-matching static bounds 13341 13342@item 13343Subprogram declaration only allowed in package spec (unless followed by import) 13344 13345@item 13346Access types not allowed 13347 13348@item 13349Incomplete type declaration not allowed 13350 13351@item 13352Object and subtype declarations must respect SPARK 2005 restrictions 13353 13354@item 13355Digits or delta constraint not allowed 13356 13357@item 13358Decimal fixed point type not allowed 13359 13360@item 13361Aliasing of objects not allowed 13362 13363@item 13364Modular type modulus must be power of 2 13365 13366@item 13367Base not allowed on subtype mark 13368 13369@item 13370Unary operators not allowed on modular types (except not) 13371 13372@item 13373Untagged record cannot be null 13374 13375@item 13376No class-wide operations 13377 13378@item 13379Initialization expressions must respect SPARK 2005 restrictions 13380 13381@item 13382Nonstatic ranges not allowed except in iteration schemes 13383 13384@item 13385String subtypes must have lower bound of 1 13386 13387@item 13388Subtype of Boolean cannot have constraint 13389 13390@item 13391At most one tagged type or extension per package 13392 13393@item 13394Interface is not allowed 13395 13396@item 13397Character literal cannot be prefixed (selector name cannot be character literal) 13398 13399@item 13400Record aggregate cannot contain 'others' 13401 13402@item 13403Component association in record aggregate must contain a single choice 13404 13405@item 13406Ancestor part cannot be a type mark 13407 13408@item 13409Attributes 'Image, 'Width and 'Value not allowed 13410 13411@item 13412Functions may not update globals 13413 13414@item 13415Subprograms may not contain direct calls to themselves (prevents recursion within unit) 13416 13417@item 13418Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit) 13419@end itemize 13420 13421The following restrictions are enforced, but note that they are actually more 13422strict that the latest SPARK 2005 language definition: 13423 13424 13425@itemize * 13426 13427@item 13428No derived types other than tagged type extensions 13429 13430@item 13431Subtype of unconstrained array must have constraint 13432@end itemize 13433 13434This list summarises the main SPARK 2005 language rules that are not 13435currently checked by the SPARK_05 restriction: 13436 13437 13438@itemize * 13439 13440@item 13441SPARK 2005 annotations are treated as comments so are not checked at all 13442 13443@item 13444Based real literals not allowed 13445 13446@item 13447Objects cannot be initialized at declaration by calls to user-defined functions 13448 13449@item 13450Objects cannot be initialized at declaration by assignments from variables 13451 13452@item 13453Objects cannot be initialized at declaration by assignments from indexed/selected components 13454 13455@item 13456Ranges shall not be null 13457 13458@item 13459A fixed point delta expression must be a simple expression 13460 13461@item 13462Restrictions on where renaming declarations may be placed 13463 13464@item 13465Externals of mode 'out' cannot be referenced 13466 13467@item 13468Externals of mode 'in' cannot be updated 13469 13470@item 13471Loop with no iteration scheme or exits only allowed as last statement in main program or task 13472 13473@item 13474Subprogram cannot have parent unit name 13475 13476@item 13477SPARK 2005 inherited subprogram must be prefixed with overriding 13478 13479@item 13480External variables (or functions that reference them) may not be passed as actual parameters 13481 13482@item 13483Globals must be explicitly mentioned in contract 13484 13485@item 13486Deferred constants cannot be completed by pragma Import 13487 13488@item 13489Package initialization cannot read/write variables from other packages 13490 13491@item 13492Prefix not allowed for entities that are directly visible 13493 13494@item 13495Identifier declaration can't override inherited package name 13496 13497@item 13498Cannot use Standard or other predefined packages as identifiers 13499 13500@item 13501After renaming, cannot use the original name 13502 13503@item 13504Subprograms can only be renamed to remove package prefix 13505 13506@item 13507Pragma import must be immediately after entity it names 13508 13509@item 13510No mutual recursion between multiple units (this can be checked with gnatcheck) 13511@end itemize 13512 13513Note that if a unit is compiled in Ada 95 mode with the SPARK 2005 restriction, 13514violations will be reported for constructs forbidden in SPARK 95, 13515instead of SPARK 2005. 13516 13517@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13518@anchor{gnat_rm/implementation_advice doc}@anchor{20c}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{20d} 13519@chapter Implementation Advice 13520 13521 13522The main text of the Ada Reference Manual describes the required 13523behavior of all Ada compilers, and the GNAT compiler conforms to 13524these requirements. 13525 13526In addition, there are sections throughout the Ada Reference Manual headed 13527by the phrase 'Implementation advice'. These sections are not normative, 13528i.e., they do not specify requirements that all compilers must 13529follow. Rather they provide advice on generally desirable behavior. 13530They are not requirements, because they describe behavior that cannot 13531be provided on all systems, or may be undesirable on some systems. 13532 13533As far as practical, GNAT follows the implementation advice in 13534the Ada Reference Manual. Each such RM section corresponds to a section 13535in this chapter whose title specifies the 13536RM section number and paragraph number and the subject of 13537the advice. The contents of each section consists of the RM text within 13538quotation marks, 13539followed by the GNAT interpretation of the advice. Most often, this simply says 13540'followed', which means that GNAT follows the advice. However, in a 13541number of cases, GNAT deliberately deviates from this advice, in which 13542case the text describes what GNAT does and why. 13543 13544@geindex Error detection 13545 13546@menu 13547* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13548* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13549* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13550* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13551* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13552* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13553* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13554* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13555* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13556* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13557* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13558* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 13559* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13560* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13561* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13562* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13563* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13564* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13565* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13566* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13567* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13568* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13569* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13570* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13571* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13572* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13573* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13574* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13575* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13576* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13577* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13578* RM 13.13.2(17); Stream Oriented Attributes: RM 13 13 2 17 Stream Oriented Attributes. 13579* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13580* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13581* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13582* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13583* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13584* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13585* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13586* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13587* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13588* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13589* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13590* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13591* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13592* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13593* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13594* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13595* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13596* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13597* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13598* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13599* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13600* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13601* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13602* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13603* RM F(7); COBOL Support: RM F 7 COBOL Support. 13604* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13605* RM G; Numerics: RM G Numerics. 13606* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13607* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13608* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13609* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13610* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13611 13612@end menu 13613 13614@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13615@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{20e} 13616@section RM 1.1.3(20): Error Detection 13617 13618 13619@quotation 13620 13621"If an implementation detects the use of an unsupported Specialized Needs 13622Annex feature at run time, it should raise @code{Program_Error} if 13623feasible." 13624@end quotation 13625 13626Not relevant. All specialized needs annex features are either supported, 13627or diagnosed at compile time. 13628 13629@geindex Child Units 13630 13631@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13632@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{20f} 13633@section RM 1.1.3(31): Child Units 13634 13635 13636@quotation 13637 13638"If an implementation wishes to provide implementation-defined 13639extensions to the functionality of a language-defined library unit, it 13640should normally do so by adding children to the library unit." 13641@end quotation 13642 13643Followed. 13644 13645@geindex Bounded errors 13646 13647@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13648@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{210} 13649@section RM 1.1.5(12): Bounded Errors 13650 13651 13652@quotation 13653 13654"If an implementation detects a bounded error or erroneous 13655execution, it should raise @code{Program_Error}." 13656@end quotation 13657 13658Followed in all cases in which the implementation detects a bounded 13659error or erroneous execution. Not all such situations are detected at 13660runtime. 13661 13662@geindex Pragmas 13663 13664@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13665@anchor{gnat_rm/implementation_advice id2}@anchor{211}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{212} 13666@section RM 2.8(16): Pragmas 13667 13668 13669@quotation 13670 13671"Normally, implementation-defined pragmas should have no semantic effect 13672for error-free programs; that is, if the implementation-defined pragmas 13673are removed from a working program, the program should still be legal, 13674and should still have the same semantics." 13675@end quotation 13676 13677The following implementation defined pragmas are exceptions to this 13678rule: 13679 13680 13681@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 13682@headitem 13683 13684Pragma 13685 13686@tab 13687 13688Explanation 13689 13690@item 13691 13692@emph{Abort_Defer} 13693 13694@tab 13695 13696Affects semantics 13697 13698@item 13699 13700@emph{Ada_83} 13701 13702@tab 13703 13704Affects legality 13705 13706@item 13707 13708@emph{Assert} 13709 13710@tab 13711 13712Affects semantics 13713 13714@item 13715 13716@emph{CPP_Class} 13717 13718@tab 13719 13720Affects semantics 13721 13722@item 13723 13724@emph{CPP_Constructor} 13725 13726@tab 13727 13728Affects semantics 13729 13730@item 13731 13732@emph{Debug} 13733 13734@tab 13735 13736Affects semantics 13737 13738@item 13739 13740@emph{Interface_Name} 13741 13742@tab 13743 13744Affects semantics 13745 13746@item 13747 13748@emph{Machine_Attribute} 13749 13750@tab 13751 13752Affects semantics 13753 13754@item 13755 13756@emph{Unimplemented_Unit} 13757 13758@tab 13759 13760Affects legality 13761 13762@item 13763 13764@emph{Unchecked_Union} 13765 13766@tab 13767 13768Affects semantics 13769 13770@end multitable 13771 13772 13773In each of the above cases, it is essential to the purpose of the pragma 13774that this advice not be followed. For details see 13775@ref{7,,Implementation Defined Pragmas}. 13776 13777@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 13778@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{213} 13779@section RM 2.8(17-19): Pragmas 13780 13781 13782@quotation 13783 13784"Normally, an implementation should not define pragmas that can 13785make an illegal program legal, except as follows: 13786 13787 13788@itemize * 13789 13790@item 13791A pragma used to complete a declaration, such as a pragma @code{Import}; 13792 13793@item 13794A pragma used to configure the environment by adding, removing, or 13795replacing @code{library_items}." 13796@end itemize 13797@end quotation 13798 13799See @ref{212,,RM 2.8(16); Pragmas}. 13800 13801@geindex Character Sets 13802 13803@geindex Alternative Character Sets 13804 13805@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 13806@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{214} 13807@section RM 3.5.2(5): Alternative Character Sets 13808 13809 13810@quotation 13811 13812"If an implementation supports a mode with alternative interpretations 13813for @code{Character} and @code{Wide_Character}, the set of graphic 13814characters of @code{Character} should nevertheless remain a proper 13815subset of the set of graphic characters of @code{Wide_Character}. Any 13816character set 'localizations' should be reflected in the results of 13817the subprograms defined in the language-defined package 13818@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 13819an alternative interpretation of @code{Character}, the implementation should 13820also support a corresponding change in what is a legal 13821@code{identifier_letter}." 13822@end quotation 13823 13824Not all wide character modes follow this advice, in particular the JIS 13825and IEC modes reflect standard usage in Japan, and in these encoding, 13826the upper half of the Latin-1 set is not part of the wide-character 13827subset, since the most significant bit is used for wide character 13828encoding. However, this only applies to the external forms. Internally 13829there is no such restriction. 13830 13831@geindex Integer types 13832 13833@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 13834@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{215} 13835@section RM 3.5.4(28): Integer Types 13836 13837 13838@quotation 13839 13840"An implementation should support @code{Long_Integer} in addition to 13841@code{Integer} if the target machine supports 32-bit (or longer) 13842arithmetic. No other named integer subtypes are recommended for package 13843@code{Standard}. Instead, appropriate named integer subtypes should be 13844provided in the library package @code{Interfaces} (see B.2)." 13845@end quotation 13846 13847@code{Long_Integer} is supported. Other standard integer types are supported 13848so this advice is not fully followed. These types 13849are supported for convenient interface to C, and so that all hardware 13850types of the machine are easily available. 13851 13852@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 13853@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{216} 13854@section RM 3.5.4(29): Integer Types 13855 13856 13857@quotation 13858 13859"An implementation for a two's complement machine should support 13860modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 13861implementation should support a non-binary modules up to @code{Integer'Last}." 13862@end quotation 13863 13864Followed. 13865 13866@geindex Enumeration values 13867 13868@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 13869@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{217} 13870@section RM 3.5.5(8): Enumeration Values 13871 13872 13873@quotation 13874 13875"For the evaluation of a call on @code{S'Pos} for an enumeration 13876subtype, if the value of the operand does not correspond to the internal 13877code for any enumeration literal of its type (perhaps due to an 13878un-initialized variable), then the implementation should raise 13879@code{Program_Error}. This is particularly important for enumeration 13880types with noncontiguous internal codes specified by an 13881enumeration_representation_clause." 13882@end quotation 13883 13884Followed. 13885 13886@geindex Float types 13887 13888@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 13889@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{218} 13890@section RM 3.5.7(17): Float Types 13891 13892 13893@quotation 13894 13895"An implementation should support @code{Long_Float} in addition to 13896@code{Float} if the target machine supports 11 or more digits of 13897precision. No other named floating point subtypes are recommended for 13898package @code{Standard}. Instead, appropriate named floating point subtypes 13899should be provided in the library package @code{Interfaces} (see B.2)." 13900@end quotation 13901 13902@code{Short_Float} and @code{Long_Long_Float} are also provided. The 13903former provides improved compatibility with other implementations 13904supporting this type. The latter corresponds to the highest precision 13905floating-point type supported by the hardware. On most machines, this 13906will be the same as @code{Long_Float}, but on some machines, it will 13907correspond to the IEEE extended form. The notable case is all ia32 13908(x86) implementations, where @code{Long_Long_Float} corresponds to 13909the 80-bit extended precision format supported in hardware on this 13910processor. Note that the 128-bit format on SPARC is not supported, 13911since this is a software rather than a hardware format. 13912 13913@geindex Multidimensional arrays 13914 13915@geindex Arrays 13916@geindex multidimensional 13917 13918@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice 13919@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{219} 13920@section RM 3.6.2(11): Multidimensional Arrays 13921 13922 13923@quotation 13924 13925"An implementation should normally represent multidimensional arrays in 13926row-major order, consistent with the notation used for multidimensional 13927array aggregates (see 4.3.3). However, if a pragma @code{Convention} 13928(@code{Fortran}, ...) applies to a multidimensional array type, then 13929column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})." 13930@end quotation 13931 13932Followed. 13933 13934@geindex Duration'Small 13935 13936@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 13937@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{21a} 13938@section RM 9.6(30-31): Duration'Small 13939 13940 13941@quotation 13942 13943"Whenever possible in an implementation, the value of @code{Duration'Small} 13944should be no greater than 100 microseconds." 13945@end quotation 13946 13947Followed. (@code{Duration'Small} = 10**(-9)). 13948 13949@quotation 13950 13951"The time base for @code{delay_relative_statements} should be monotonic; 13952it need not be the same time base as used for @code{Calendar.Clock}." 13953@end quotation 13954 13955Followed. 13956 13957@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice 13958@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{21b} 13959@section RM 10.2.1(12): Consistent Representation 13960 13961 13962@quotation 13963 13964"In an implementation, a type declared in a pre-elaborated package should 13965have the same representation in every elaboration of a given version of 13966the package, whether the elaborations occur in distinct executions of 13967the same program, or in executions of distinct programs or partitions 13968that include the given version." 13969@end quotation 13970 13971Followed, except in the case of tagged types. Tagged types involve 13972implicit pointers to a local copy of a dispatch table, and these pointers 13973have representations which thus depend on a particular elaboration of the 13974package. It is not easy to see how it would be possible to follow this 13975advice without severely impacting efficiency of execution. 13976 13977@geindex Exception information 13978 13979@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 13980@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{21c} 13981@section RM 11.4.1(19): Exception Information 13982 13983 13984@quotation 13985 13986"@code{Exception_Message} by default and @code{Exception_Information} 13987should produce information useful for 13988debugging. @code{Exception_Message} should be short, about one 13989line. @code{Exception_Information} can be long. @code{Exception_Message} 13990should not include the 13991@code{Exception_Name}. @code{Exception_Information} should include both 13992the @code{Exception_Name} and the @code{Exception_Message}." 13993@end quotation 13994 13995Followed. For each exception that doesn't have a specified 13996@code{Exception_Message}, the compiler generates one containing the location 13997of the raise statement. This location has the form 'file_name:line', where 13998file_name is the short file name (without path information) and line is the line 13999number in the file. Note that in the case of the Zero Cost Exception 14000mechanism, these messages become redundant with the Exception_Information that 14001contains a full backtrace of the calling sequence, so they are disabled. 14002To disable explicitly the generation of the source location message, use the 14003Pragma @code{Discard_Names}. 14004 14005@geindex Suppression of checks 14006 14007@geindex Checks 14008@geindex suppression of 14009 14010@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 14011@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{21d} 14012@section RM 11.5(28): Suppression of Checks 14013 14014 14015@quotation 14016 14017"The implementation should minimize the code executed for checks that 14018have been suppressed." 14019@end quotation 14020 14021Followed. 14022 14023@geindex Representation clauses 14024 14025@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 14026@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{21e} 14027@section RM 13.1 (21-24): Representation Clauses 14028 14029 14030@quotation 14031 14032"The recommended level of support for all representation items is 14033qualified as follows: 14034 14035An implementation need not support representation items containing 14036nonstatic expressions, except that an implementation should support a 14037representation item for a given entity if each nonstatic expression in 14038the representation item is a name that statically denotes a constant 14039declared before the entity." 14040@end quotation 14041 14042Followed. In fact, GNAT goes beyond the recommended level of support 14043by allowing nonstatic expressions in some representation clauses even 14044without the need to declare constants initialized with the values of 14045such expressions. 14046For example: 14047 14048@example 14049 X : Integer; 14050 Y : Float; 14051 for Y'Address use X'Address;>> 14052 14053 14054"An implementation need not support a specification for the `@w{`}Size`@w{`} 14055for a given composite subtype, nor the size or storage place for an 14056object (including a component) of a given composite subtype, unless the 14057constraints on the subtype and its composite subcomponents (if any) are 14058all static constraints." 14059@end example 14060 14061Followed. Size Clauses are not permitted on nonstatic components, as 14062described above. 14063 14064@quotation 14065 14066"An aliased component, or a component whose type is by-reference, should 14067always be allocated at an addressable location." 14068@end quotation 14069 14070Followed. 14071 14072@geindex Packed types 14073 14074@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 14075@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{21f} 14076@section RM 13.2(6-8): Packed Types 14077 14078 14079@quotation 14080 14081"If a type is packed, then the implementation should try to minimize 14082storage allocated to objects of the type, possibly at the expense of 14083speed of accessing components, subject to reasonable complexity in 14084addressing calculations. 14085 14086The recommended level of support pragma @code{Pack} is: 14087 14088For a packed record type, the components should be packed as tightly as 14089possible subject to the Sizes of the component subtypes, and subject to 14090any @emph{record_representation_clause} that applies to the type; the 14091implementation may, but need not, reorder components or cross aligned 14092word boundaries to improve the packing. A component whose @code{Size} is 14093greater than the word size may be allocated an integral number of words." 14094@end quotation 14095 14096Followed. Tight packing of arrays is supported for all component sizes 14097up to 64-bits. If the array component size is 1 (that is to say, if 14098the component is a boolean type or an enumeration type with two values) 14099then values of the type are implicitly initialized to zero. This 14100happens both for objects of the packed type, and for objects that have a 14101subcomponent of the packed type. 14102 14103@quotation 14104 14105"An implementation should support Address clauses for imported 14106subprograms." 14107@end quotation 14108 14109Followed. 14110 14111@geindex Address clauses 14112 14113@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 14114@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{220} 14115@section RM 13.3(14-19): Address Clauses 14116 14117 14118@quotation 14119 14120"For an array @code{X}, @code{X'Address} should point at the first 14121component of the array, and not at the array bounds." 14122@end quotation 14123 14124Followed. 14125 14126@quotation 14127 14128"The recommended level of support for the @code{Address} attribute is: 14129 14130@code{X'Address} should produce a useful result if @code{X} is an 14131object that is aliased or of a by-reference type, or is an entity whose 14132@code{Address} has been specified." 14133@end quotation 14134 14135Followed. A valid address will be produced even if none of those 14136conditions have been met. If necessary, the object is forced into 14137memory to ensure the address is valid. 14138 14139@quotation 14140 14141"An implementation should support @code{Address} clauses for imported 14142subprograms." 14143@end quotation 14144 14145Followed. 14146 14147@quotation 14148 14149"Objects (including subcomponents) that are aliased or of a by-reference 14150type should be allocated on storage element boundaries." 14151@end quotation 14152 14153Followed. 14154 14155@quotation 14156 14157"If the @code{Address} of an object is specified, or it is imported or exported, 14158then the implementation should not perform optimizations based on 14159assumptions of no aliases." 14160@end quotation 14161 14162Followed. 14163 14164@geindex Alignment clauses 14165 14166@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 14167@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{221} 14168@section RM 13.3(29-35): Alignment Clauses 14169 14170 14171@quotation 14172 14173"The recommended level of support for the @code{Alignment} attribute for 14174subtypes is: 14175 14176An implementation should support specified Alignments that are factors 14177and multiples of the number of storage elements per word, subject to the 14178following:" 14179@end quotation 14180 14181Followed. 14182 14183@quotation 14184 14185"An implementation need not support specified Alignments for 14186combinations of Sizes and Alignments that cannot be easily 14187loaded and stored by available machine instructions." 14188@end quotation 14189 14190Followed. 14191 14192@quotation 14193 14194"An implementation need not support specified Alignments that are 14195greater than the maximum @code{Alignment} the implementation ever returns by 14196default." 14197@end quotation 14198 14199Followed. 14200 14201@quotation 14202 14203"The recommended level of support for the @code{Alignment} attribute for 14204objects is: 14205 14206Same as above, for subtypes, but in addition:" 14207@end quotation 14208 14209Followed. 14210 14211@quotation 14212 14213"For stand-alone library-level objects of statically constrained 14214subtypes, the implementation should support all alignments 14215supported by the target linker. For example, page alignment is likely to 14216be supported for such objects, but not for subtypes." 14217@end quotation 14218 14219Followed. 14220 14221@geindex Size clauses 14222 14223@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 14224@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{222} 14225@section RM 13.3(42-43): Size Clauses 14226 14227 14228@quotation 14229 14230"The recommended level of support for the @code{Size} attribute of 14231objects is: 14232 14233A @code{Size} clause should be supported for an object if the specified 14234@code{Size} is at least as large as its subtype's @code{Size}, and 14235corresponds to a size in storage elements that is a multiple of the 14236object's @code{Alignment} (if the @code{Alignment} is nonzero)." 14237@end quotation 14238 14239Followed. 14240 14241@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 14242@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{223} 14243@section RM 13.3(50-56): Size Clauses 14244 14245 14246@quotation 14247 14248"If the @code{Size} of a subtype is specified, and allows for efficient 14249independent addressability (see 9.10) on the target architecture, then 14250the @code{Size} of the following objects of the subtype should equal the 14251@code{Size} of the subtype: 14252 14253Aliased objects (including components)." 14254@end quotation 14255 14256Followed. 14257 14258@quotation 14259 14260"@cite{Size} clause on a composite subtype should not affect the 14261internal layout of components." 14262@end quotation 14263 14264Followed. But note that this can be overridden by use of the implementation 14265pragma Implicit_Packing in the case of packed arrays. 14266 14267@quotation 14268 14269"The recommended level of support for the @code{Size} attribute of subtypes is: 14270 14271The @code{Size} (if not specified) of a static discrete or fixed point 14272subtype should be the number of bits needed to represent each value 14273belonging to the subtype using an unbiased representation, leaving space 14274for a sign bit only if the subtype contains negative values. If such a 14275subtype is a first subtype, then an implementation should support a 14276specified @code{Size} for it that reflects this representation." 14277@end quotation 14278 14279Followed. 14280 14281@quotation 14282 14283"For a subtype implemented with levels of indirection, the @code{Size} 14284should include the size of the pointers, but not the size of what they 14285point at." 14286@end quotation 14287 14288Followed. 14289 14290@geindex Component_Size clauses 14291 14292@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 14293@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{224} 14294@section RM 13.3(71-73): Component Size Clauses 14295 14296 14297@quotation 14298 14299"The recommended level of support for the @code{Component_Size} 14300attribute is: 14301 14302An implementation need not support specified @code{Component_Sizes} that are 14303less than the @code{Size} of the component subtype." 14304@end quotation 14305 14306Followed. 14307 14308@quotation 14309 14310"An implementation should support specified Component_Sizes that 14311are factors and multiples of the word size. For such 14312Component_Sizes, the array should contain no gaps between 14313components. For other Component_Sizes (if supported), the array 14314should contain no gaps between components when packing is also 14315specified; the implementation should forbid this combination in cases 14316where it cannot support a no-gaps representation." 14317@end quotation 14318 14319Followed. 14320 14321@geindex Enumeration representation clauses 14322 14323@geindex Representation clauses 14324@geindex enumeration 14325 14326@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 14327@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{225} 14328@section RM 13.4(9-10): Enumeration Representation Clauses 14329 14330 14331@quotation 14332 14333"The recommended level of support for enumeration representation clauses 14334is: 14335 14336An implementation need not support enumeration representation clauses 14337for boolean types, but should at minimum support the internal codes in 14338the range @code{System.Min_Int .. System.Max_Int}." 14339@end quotation 14340 14341Followed. 14342 14343@geindex Record representation clauses 14344 14345@geindex Representation clauses 14346@geindex records 14347 14348@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 14349@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{226} 14350@section RM 13.5.1(17-22): Record Representation Clauses 14351 14352 14353@quotation 14354 14355"The recommended level of support for 14356@emph{record_representation_clause}s is: 14357 14358An implementation should support storage places that can be extracted 14359with a load, mask, shift sequence of machine code, and set with a load, 14360shift, mask, store sequence, given the available machine instructions 14361and run-time model." 14362@end quotation 14363 14364Followed. 14365 14366@quotation 14367 14368"A storage place should be supported if its size is equal to the 14369@code{Size} of the component subtype, and it starts and ends on a 14370boundary that obeys the @code{Alignment} of the component subtype." 14371@end quotation 14372 14373Followed. 14374 14375@quotation 14376 14377"If the default bit ordering applies to the declaration of a given type, 14378then for a component whose subtype's @code{Size} is less than the word 14379size, any storage place that does not cross an aligned word boundary 14380should be supported." 14381@end quotation 14382 14383Followed. 14384 14385@quotation 14386 14387"An implementation may reserve a storage place for the tag field of a 14388tagged type, and disallow other components from overlapping that place." 14389@end quotation 14390 14391Followed. The storage place for the tag field is the beginning of the tagged 14392record, and its size is Address'Size. GNAT will reject an explicit component 14393clause for the tag field. 14394 14395@quotation 14396 14397"An implementation need not support a @emph{component_clause} for a 14398component of an extension part if the storage place is not after the 14399storage places of all components of the parent type, whether or not 14400those storage places had been specified." 14401@end quotation 14402 14403Followed. The above advice on record representation clauses is followed, 14404and all mentioned features are implemented. 14405 14406@geindex Storage place attributes 14407 14408@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 14409@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{227} 14410@section RM 13.5.2(5): Storage Place Attributes 14411 14412 14413@quotation 14414 14415"If a component is represented using some form of pointer (such as an 14416offset) to the actual data of the component, and this data is contiguous 14417with the rest of the object, then the storage place attributes should 14418reflect the place of the actual data, not the pointer. If a component is 14419allocated discontinuously from the rest of the object, then a warning 14420should be generated upon reference to one of its storage place 14421attributes." 14422@end quotation 14423 14424Followed. There are no such components in GNAT. 14425 14426@geindex Bit ordering 14427 14428@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 14429@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{228} 14430@section RM 13.5.3(7-8): Bit Ordering 14431 14432 14433@quotation 14434 14435"The recommended level of support for the non-default bit ordering is: 14436 14437If @code{Word_Size} = @code{Storage_Unit}, then the implementation 14438should support the non-default bit ordering in addition to the default 14439bit ordering." 14440@end quotation 14441 14442Followed. Word size does not equal storage size in this implementation. 14443Thus non-default bit ordering is not supported. 14444 14445@geindex Address 14446@geindex as private type 14447 14448@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 14449@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{229} 14450@section RM 13.7(37): Address as Private 14451 14452 14453@quotation 14454 14455"@cite{Address} should be of a private type." 14456@end quotation 14457 14458Followed. 14459 14460@geindex Operations 14461@geindex on `@w{`}Address`@w{`} 14462 14463@geindex Address 14464@geindex operations of 14465 14466@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14467@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{22a} 14468@section RM 13.7.1(16): Address Operations 14469 14470 14471@quotation 14472 14473"Operations in @code{System} and its children should reflect the target 14474environment semantics as closely as is reasonable. For example, on most 14475machines, it makes sense for address arithmetic to 'wrap around'. 14476Operations that do not make sense should raise @code{Program_Error}." 14477@end quotation 14478 14479Followed. Address arithmetic is modular arithmetic that wraps around. No 14480operation raises @code{Program_Error}, since all operations make sense. 14481 14482@geindex Unchecked conversion 14483 14484@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 14485@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{22b} 14486@section RM 13.9(14-17): Unchecked Conversion 14487 14488 14489@quotation 14490 14491"The @code{Size} of an array object should not include its bounds; hence, 14492the bounds should not be part of the converted data." 14493@end quotation 14494 14495Followed. 14496 14497@quotation 14498 14499"The implementation should not generate unnecessary run-time checks to 14500ensure that the representation of @code{S} is a representation of the 14501target type. It should take advantage of the permission to return by 14502reference when possible. Restrictions on unchecked conversions should be 14503avoided unless required by the target environment." 14504@end quotation 14505 14506Followed. There are no restrictions on unchecked conversion. A warning is 14507generated if the source and target types do not have the same size since 14508the semantics in this case may be target dependent. 14509 14510@quotation 14511 14512"The recommended level of support for unchecked conversions is: 14513 14514Unchecked conversions should be supported and should be reversible in 14515the cases where this clause defines the result. To enable meaningful use 14516of unchecked conversion, a contiguous representation should be used for 14517elementary subtypes, for statically constrained array subtypes whose 14518component subtype is one of the subtypes described in this paragraph, 14519and for record subtypes without discriminants whose component subtypes 14520are described in this paragraph." 14521@end quotation 14522 14523Followed. 14524 14525@geindex Heap usage 14526@geindex implicit 14527 14528@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 14529@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{22c} 14530@section RM 13.11(23-25): Implicit Heap Usage 14531 14532 14533@quotation 14534 14535"An implementation should document any cases in which it dynamically 14536allocates heap storage for a purpose other than the evaluation of an 14537allocator." 14538@end quotation 14539 14540Followed, the only other points at which heap storage is dynamically 14541allocated are as follows: 14542 14543 14544@itemize * 14545 14546@item 14547At initial elaboration time, to allocate dynamically sized global 14548objects. 14549 14550@item 14551To allocate space for a task when a task is created. 14552 14553@item 14554To extend the secondary stack dynamically when needed. The secondary 14555stack is used for returning variable length results. 14556@end itemize 14557 14558 14559@quotation 14560 14561"A default (implementation-provided) storage pool for an 14562access-to-constant type should not have overhead to support deallocation of 14563individual objects." 14564@end quotation 14565 14566Followed. 14567 14568@quotation 14569 14570"A storage pool for an anonymous access type should be created at the 14571point of an allocator for the type, and be reclaimed when the designated 14572object becomes inaccessible." 14573@end quotation 14574 14575Followed. 14576 14577@geindex Unchecked deallocation 14578 14579@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 17 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice 14580@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{22d} 14581@section RM 13.11.2(17): Unchecked Deallocation 14582 14583 14584@quotation 14585 14586"For a standard storage pool, @code{Free} should actually reclaim the 14587storage." 14588@end quotation 14589 14590Followed. 14591 14592@geindex Stream oriented attributes 14593 14594@node RM 13 13 2 17 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice 14595@anchor{gnat_rm/implementation_advice rm-13-13-2-17-stream-oriented-attributes}@anchor{22e} 14596@section RM 13.13.2(17): Stream Oriented Attributes 14597 14598 14599@quotation 14600 14601"If a stream element is the same size as a storage element, then the 14602normal in-memory representation should be used by @code{Read} and 14603@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} 14604should use the smallest number of stream elements needed to represent 14605all values in the base range of the scalar type." 14606@end quotation 14607 14608Followed. By default, GNAT uses the interpretation suggested by AI-195, 14609which specifies using the size of the first subtype. 14610However, such an implementation is based on direct binary 14611representations and is therefore target- and endianness-dependent. 14612To address this issue, GNAT also supplies an alternate implementation 14613of the stream attributes @code{Read} and @code{Write}, 14614which uses the target-independent XDR standard representation 14615for scalar types. 14616 14617@geindex XDR representation 14618 14619@geindex Read attribute 14620 14621@geindex Write attribute 14622 14623@geindex Stream oriented attributes 14624 14625The XDR implementation is provided as an alternative body of the 14626@code{System.Stream_Attributes} package, in the file 14627@code{s-stratt-xdr.adb} in the GNAT library. 14628There is no @code{s-stratt-xdr.ads} file. 14629In order to install the XDR implementation, do the following: 14630 14631 14632@itemize * 14633 14634@item 14635Replace the default implementation of the 14636@code{System.Stream_Attributes} package with the XDR implementation. 14637For example on a Unix platform issue the commands: 14638 14639@example 14640$ mv s-stratt.adb s-stratt-default.adb 14641$ mv s-stratt-xdr.adb s-stratt.adb 14642@end example 14643 14644@item 14645Rebuild the GNAT run-time library as documented in 14646the @emph{GNAT and Libraries} section of the @cite{GNAT User's Guide}. 14647@end itemize 14648 14649@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 17 Stream Oriented Attributes,Implementation Advice 14650@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{22f} 14651@section RM A.1(52): Names of Predefined Numeric Types 14652 14653 14654@quotation 14655 14656"If an implementation provides additional named predefined integer types, 14657then the names should end with @code{Integer} as in 14658@code{Long_Integer}. If an implementation provides additional named 14659predefined floating point types, then the names should end with 14660@code{Float} as in @code{Long_Float}." 14661@end quotation 14662 14663Followed. 14664 14665@geindex Ada.Characters.Handling 14666 14667@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 14668@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{230} 14669@section RM A.3.2(49): @code{Ada.Characters.Handling} 14670 14671 14672@quotation 14673 14674"If an implementation provides a localized definition of @code{Character} 14675or @code{Wide_Character}, then the effects of the subprograms in 14676@code{Characters.Handling} should reflect the localizations. 14677See also 3.5.2." 14678@end quotation 14679 14680Followed. GNAT provides no such localized definitions. 14681 14682@geindex Bounded-length strings 14683 14684@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 14685@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{231} 14686@section RM A.4.4(106): Bounded-Length String Handling 14687 14688 14689@quotation 14690 14691"Bounded string objects should not be implemented by implicit pointers 14692and dynamic allocation." 14693@end quotation 14694 14695Followed. No implicit pointers or dynamic allocation are used. 14696 14697@geindex Random number generation 14698 14699@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 14700@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{232} 14701@section RM A.5.2(46-47): Random Number Generation 14702 14703 14704@quotation 14705 14706"Any storage associated with an object of type @code{Generator} should be 14707reclaimed on exit from the scope of the object." 14708@end quotation 14709 14710Followed. 14711 14712@quotation 14713 14714"If the generator period is sufficiently long in relation to the number 14715of distinct initiator values, then each possible value of 14716@code{Initiator} passed to @code{Reset} should initiate a sequence of 14717random numbers that does not, in a practical sense, overlap the sequence 14718initiated by any other value. If this is not possible, then the mapping 14719between initiator values and generator states should be a rapidly 14720varying function of the initiator value." 14721@end quotation 14722 14723Followed. The generator period is sufficiently long for the first 14724condition here to hold true. 14725 14726@geindex Get_Immediate 14727 14728@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 14729@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{233} 14730@section RM A.10.7(23): @code{Get_Immediate} 14731 14732 14733@quotation 14734 14735"The @code{Get_Immediate} procedures should be implemented with 14736unbuffered input. For a device such as a keyboard, input should be 14737available if a key has already been typed, whereas for a disk 14738file, input should always be available except at end of file. For a file 14739associated with a keyboard-like device, any line-editing features of the 14740underlying operating system should be disabled during the execution of 14741@code{Get_Immediate}." 14742@end quotation 14743 14744Followed on all targets except VxWorks. For VxWorks, there is no way to 14745provide this functionality that does not result in the input buffer being 14746flushed before the @code{Get_Immediate} call. A special unit 14747@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 14748this functionality. 14749 14750@geindex Export 14751 14752@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice 14753@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{234} 14754@section RM B.1(39-41): Pragma @code{Export} 14755 14756 14757@quotation 14758 14759"If an implementation supports pragma @code{Export} to a given language, 14760then it should also allow the main subprogram to be written in that 14761language. It should support some mechanism for invoking the elaboration 14762of the Ada library units included in the system, and for invoking the 14763finalization of the environment task. On typical systems, the 14764recommended mechanism is to provide two subprograms whose link names are 14765@code{adainit} and @code{adafinal}. @code{adainit} should contain the 14766elaboration code for library units. @code{adafinal} should contain the 14767finalization code. These subprograms should have no effect the second 14768and subsequent time they are called." 14769@end quotation 14770 14771Followed. 14772 14773@quotation 14774 14775"Automatic elaboration of pre-elaborated packages should be 14776provided when pragma @code{Export} is supported." 14777@end quotation 14778 14779Followed when the main program is in Ada. If the main program is in a 14780foreign language, then 14781@code{adainit} must be called to elaborate pre-elaborated 14782packages. 14783 14784@quotation 14785 14786"For each supported convention @emph{L} other than @code{Intrinsic}, an 14787implementation should support @code{Import} and @code{Export} pragmas 14788for objects of @emph{L}-compatible types and for subprograms, and pragma 14789@cite{Convention} for @emph{L}-eligible types and for subprograms, 14790presuming the other language has corresponding features. Pragma 14791@code{Convention} need not be supported for scalar types." 14792@end quotation 14793 14794Followed. 14795 14796@geindex Package Interfaces 14797 14798@geindex Interfaces 14799 14800@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 14801@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{235} 14802@section RM B.2(12-13): Package @code{Interfaces} 14803 14804 14805@quotation 14806 14807"For each implementation-defined convention identifier, there should be a 14808child package of package Interfaces with the corresponding name. This 14809package should contain any declarations that would be useful for 14810interfacing to the language (implementation) represented by the 14811convention. Any declarations useful for interfacing to any language on 14812the given hardware architecture should be provided directly in 14813@code{Interfaces}." 14814@end quotation 14815 14816Followed. 14817 14818@quotation 14819 14820"An implementation supporting an interface to C, COBOL, or Fortran should 14821provide the corresponding package or packages described in the following 14822clauses." 14823@end quotation 14824 14825Followed. GNAT provides all the packages described in this section. 14826 14827@geindex C 14828@geindex interfacing with 14829 14830@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 14831@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{236} 14832@section RM B.3(63-71): Interfacing with C 14833 14834 14835@quotation 14836 14837"An implementation should support the following interface correspondences 14838between Ada and C." 14839@end quotation 14840 14841Followed. 14842 14843@quotation 14844 14845"An Ada procedure corresponds to a void-returning C function." 14846@end quotation 14847 14848Followed. 14849 14850@quotation 14851 14852"An Ada function corresponds to a non-void C function." 14853@end quotation 14854 14855Followed. 14856 14857@quotation 14858 14859"An Ada @code{in} scalar parameter is passed as a scalar argument to a C 14860function." 14861@end quotation 14862 14863Followed. 14864 14865@quotation 14866 14867"An Ada @code{in} parameter of an access-to-object type with designated 14868type @code{T} is passed as a @code{t*} argument to a C function, 14869where @code{t} is the C type corresponding to the Ada type @code{T}." 14870@end quotation 14871 14872Followed. 14873 14874@quotation 14875 14876"An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} 14877parameter of an elementary type @code{T}, is passed as a @code{t*} 14878argument to a C function, where @code{t} is the C type corresponding to 14879the Ada type @code{T}. In the case of an elementary @code{out} or 14880@code{in out} parameter, a pointer to a temporary copy is used to 14881preserve by-copy semantics." 14882@end quotation 14883 14884Followed. 14885 14886@quotation 14887 14888"An Ada parameter of a record type @code{T}, of any mode, is passed as a 14889@code{t*} argument to a C function, where @code{t} is the C 14890structure corresponding to the Ada type @code{T}." 14891@end quotation 14892 14893Followed. This convention may be overridden by the use of the C_Pass_By_Copy 14894pragma, or Convention, or by explicitly specifying the mechanism for a given 14895call using an extended import or export pragma. 14896 14897@quotation 14898 14899"An Ada parameter of an array type with component type @code{T}, of any 14900mode, is passed as a @code{t*} argument to a C function, where 14901@code{t} is the C type corresponding to the Ada type @code{T}." 14902@end quotation 14903 14904Followed. 14905 14906@quotation 14907 14908"An Ada parameter of an access-to-subprogram type is passed as a pointer 14909to a C function whose prototype corresponds to the designated 14910subprogram's specification." 14911@end quotation 14912 14913Followed. 14914 14915@geindex COBOL 14916@geindex interfacing with 14917 14918@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 14919@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{237} 14920@section RM B.4(95-98): Interfacing with COBOL 14921 14922 14923@quotation 14924 14925"An Ada implementation should support the following interface 14926correspondences between Ada and COBOL." 14927@end quotation 14928 14929Followed. 14930 14931@quotation 14932 14933"An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of 14934the COBOL type corresponding to @code{T}." 14935@end quotation 14936 14937Followed. 14938 14939@quotation 14940 14941"An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 14942the corresponding COBOL type." 14943@end quotation 14944 14945Followed. 14946 14947@quotation 14948 14949"Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 14950COBOL type corresponding to the Ada parameter type; for scalars, a local 14951copy is used if necessary to ensure by-copy semantics." 14952@end quotation 14953 14954Followed. 14955 14956@geindex Fortran 14957@geindex interfacing with 14958 14959@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 14960@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{238} 14961@section RM B.5(22-26): Interfacing with Fortran 14962 14963 14964@quotation 14965 14966"An Ada implementation should support the following interface 14967correspondences between Ada and Fortran:" 14968@end quotation 14969 14970Followed. 14971 14972@quotation 14973 14974"An Ada procedure corresponds to a Fortran subroutine." 14975@end quotation 14976 14977Followed. 14978 14979@quotation 14980 14981"An Ada function corresponds to a Fortran function." 14982@end quotation 14983 14984Followed. 14985 14986@quotation 14987 14988"An Ada parameter of an elementary, array, or record type @code{T} is 14989passed as a @code{T} argument to a Fortran procedure, where @code{T} is 14990the Fortran type corresponding to the Ada type @code{T}, and where the 14991INTENT attribute of the corresponding dummy argument matches the Ada 14992formal parameter mode; the Fortran implementation's parameter passing 14993conventions are used. For elementary types, a local copy is used if 14994necessary to ensure by-copy semantics." 14995@end quotation 14996 14997Followed. 14998 14999@quotation 15000 15001"An Ada parameter of an access-to-subprogram type is passed as a 15002reference to a Fortran procedure whose interface corresponds to the 15003designated subprogram's specification." 15004@end quotation 15005 15006Followed. 15007 15008@geindex Machine operations 15009 15010@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 15011@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{239} 15012@section RM C.1(3-5): Access to Machine Operations 15013 15014 15015@quotation 15016 15017"The machine code or intrinsic support should allow access to all 15018operations normally available to assembly language programmers for the 15019target environment, including privileged instructions, if any." 15020@end quotation 15021 15022Followed. 15023 15024@quotation 15025 15026"The interfacing pragmas (see Annex B) should support interface to 15027assembler; the default assembler should be associated with the 15028convention identifier @code{Assembler}." 15029@end quotation 15030 15031Followed. 15032 15033@quotation 15034 15035"If an entity is exported to assembly language, then the implementation 15036should allocate it at an addressable location, and should ensure that it 15037is retained by the linking process, even if not otherwise referenced 15038from the Ada code. The implementation should assume that any call to a 15039machine code or assembler subprogram is allowed to read or update every 15040object that is specified as exported." 15041@end quotation 15042 15043Followed. 15044 15045@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 15046@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{23a} 15047@section RM C.1(10-16): Access to Machine Operations 15048 15049 15050@quotation 15051 15052"The implementation should ensure that little or no overhead is 15053associated with calling intrinsic and machine-code subprograms." 15054@end quotation 15055 15056Followed for both intrinsics and machine-code subprograms. 15057 15058@quotation 15059 15060"It is recommended that intrinsic subprograms be provided for convenient 15061access to any machine operations that provide special capabilities or 15062efficiency and that are not otherwise available through the language 15063constructs." 15064@end quotation 15065 15066Followed. A full set of machine operation intrinsic subprograms is provided. 15067 15068@quotation 15069 15070"Atomic read-modify-write operations---e.g., test and set, compare and 15071swap, decrement and test, enqueue/dequeue." 15072@end quotation 15073 15074Followed on any target supporting such operations. 15075 15076@quotation 15077 15078"Standard numeric functions---e.g.:, sin, log." 15079@end quotation 15080 15081Followed on any target supporting such operations. 15082 15083@quotation 15084 15085"String manipulation operations---e.g.:, translate and test." 15086@end quotation 15087 15088Followed on any target supporting such operations. 15089 15090@quotation 15091 15092"Vector operations---e.g.:, compare vector against thresholds." 15093@end quotation 15094 15095Followed on any target supporting such operations. 15096 15097@quotation 15098 15099"Direct operations on I/O ports." 15100@end quotation 15101 15102Followed on any target supporting such operations. 15103 15104@geindex Interrupt support 15105 15106@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 15107@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{23b} 15108@section RM C.3(28): Interrupt Support 15109 15110 15111@quotation 15112 15113"If the @code{Ceiling_Locking} policy is not in effect, the 15114implementation should provide means for the application to specify which 15115interrupts are to be blocked during protected actions, if the underlying 15116system allows for a finer-grain control of interrupt blocking." 15117@end quotation 15118 15119Followed. The underlying system does not allow for finer-grain control 15120of interrupt blocking. 15121 15122@geindex Protected procedure handlers 15123 15124@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 15125@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{23c} 15126@section RM C.3.1(20-21): Protected Procedure Handlers 15127 15128 15129@quotation 15130 15131"Whenever possible, the implementation should allow interrupt handlers to 15132be called directly by the hardware." 15133@end quotation 15134 15135Followed on any target where the underlying operating system permits 15136such direct calls. 15137 15138@quotation 15139 15140"Whenever practical, violations of any 15141implementation-defined restrictions should be detected before run time." 15142@end quotation 15143 15144Followed. Compile time warnings are given when possible. 15145 15146@geindex Package `@w{`}Interrupts`@w{`} 15147 15148@geindex Interrupts 15149 15150@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 15151@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{23d} 15152@section RM C.3.2(25): Package @code{Interrupts} 15153 15154 15155@quotation 15156 15157"If implementation-defined forms of interrupt handler procedures are 15158supported, such as protected procedures with parameters, then for each 15159such form of a handler, a type analogous to @code{Parameterless_Handler} 15160should be specified in a child package of @code{Interrupts}, with the 15161same operations as in the predefined package Interrupts." 15162@end quotation 15163 15164Followed. 15165 15166@geindex Pre-elaboration requirements 15167 15168@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 15169@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{23e} 15170@section RM C.4(14): Pre-elaboration Requirements 15171 15172 15173@quotation 15174 15175"It is recommended that pre-elaborated packages be implemented in such a 15176way that there should be little or no code executed at run time for the 15177elaboration of entities not already covered by the Implementation 15178Requirements." 15179@end quotation 15180 15181Followed. Executable code is generated in some cases, e.g., loops 15182to initialize large arrays. 15183 15184@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 15185@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{23f} 15186@section RM C.5(8): Pragma @code{Discard_Names} 15187 15188 15189@quotation 15190 15191"If the pragma applies to an entity, then the implementation should 15192reduce the amount of storage used for storing names associated with that 15193entity." 15194@end quotation 15195 15196Followed. 15197 15198@geindex Package Task_Attributes 15199 15200@geindex Task_Attributes 15201 15202@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 15203@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{240} 15204@section RM C.7.2(30): The Package Task_Attributes 15205 15206 15207@quotation 15208 15209"Some implementations are targeted to domains in which memory use at run 15210time must be completely deterministic. For such implementations, it is 15211recommended that the storage for task attributes will be pre-allocated 15212statically and not from the heap. This can be accomplished by either 15213placing restrictions on the number and the size of the task's 15214attributes, or by using the pre-allocated storage for the first @code{N} 15215attribute objects, and the heap for the others. In the latter case, 15216@code{N} should be documented." 15217@end quotation 15218 15219Not followed. This implementation is not targeted to such a domain. 15220 15221@geindex Locking Policies 15222 15223@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 15224@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{241} 15225@section RM D.3(17): Locking Policies 15226 15227 15228@quotation 15229 15230"The implementation should use names that end with @code{_Locking} for 15231locking policies defined by the implementation." 15232@end quotation 15233 15234Followed. Two implementation-defined locking policies are defined, 15235whose names (@code{Inheritance_Locking} and 15236@code{Concurrent_Readers_Locking}) follow this suggestion. 15237 15238@geindex Entry queuing policies 15239 15240@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 15241@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{242} 15242@section RM D.4(16): Entry Queuing Policies 15243 15244 15245@quotation 15246 15247"Names that end with @code{_Queuing} should be used 15248for all implementation-defined queuing policies." 15249@end quotation 15250 15251Followed. No such implementation-defined queuing policies exist. 15252 15253@geindex Preemptive abort 15254 15255@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 15256@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{243} 15257@section RM D.6(9-10): Preemptive Abort 15258 15259 15260@quotation 15261 15262"Even though the @emph{abort_statement} is included in the list of 15263potentially blocking operations (see 9.5.1), it is recommended that this 15264statement be implemented in a way that never requires the task executing 15265the @emph{abort_statement} to block." 15266@end quotation 15267 15268Followed. 15269 15270@quotation 15271 15272"On a multi-processor, the delay associated with aborting a task on 15273another processor should be bounded; the implementation should use 15274periodic polling, if necessary, to achieve this." 15275@end quotation 15276 15277Followed. 15278 15279@geindex Tasking restrictions 15280 15281@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 15282@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{244} 15283@section RM D.7(21): Tasking Restrictions 15284 15285 15286@quotation 15287 15288"When feasible, the implementation should take advantage of the specified 15289restrictions to produce a more efficient implementation." 15290@end quotation 15291 15292GNAT currently takes advantage of these restrictions by providing an optimized 15293run time when the Ravenscar profile and the GNAT restricted run time set 15294of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 15295pragma @code{Profile (Restricted)} for more details. 15296 15297@geindex Time 15298@geindex monotonic 15299 15300@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 15301@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{245} 15302@section RM D.8(47-49): Monotonic Time 15303 15304 15305@quotation 15306 15307"When appropriate, implementations should provide configuration 15308mechanisms to change the value of @code{Tick}." 15309@end quotation 15310 15311Such configuration mechanisms are not appropriate to this implementation 15312and are thus not supported. 15313 15314@quotation 15315 15316"It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 15317be implemented as transformations of the same time base." 15318@end quotation 15319 15320Followed. 15321 15322@quotation 15323 15324"It is recommended that the best time base which exists in 15325the underlying system be available to the application through 15326@code{Clock}. @cite{Best} may mean highest accuracy or largest range." 15327@end quotation 15328 15329Followed. 15330 15331@geindex Partition communication subsystem 15332 15333@geindex PCS 15334 15335@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 15336@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{246} 15337@section RM E.5(28-29): Partition Communication Subsystem 15338 15339 15340@quotation 15341 15342"Whenever possible, the PCS on the called partition should allow for 15343multiple tasks to call the RPC-receiver with different messages and 15344should allow them to block until the corresponding subprogram body 15345returns." 15346@end quotation 15347 15348Followed by GLADE, a separately supplied PCS that can be used with 15349GNAT. 15350 15351@quotation 15352 15353"The @code{Write} operation on a stream of type @code{Params_Stream_Type} 15354should raise @code{Storage_Error} if it runs out of space trying to 15355write the @code{Item} into the stream." 15356@end quotation 15357 15358Followed by GLADE, a separately supplied PCS that can be used with 15359GNAT. 15360 15361@geindex COBOL support 15362 15363@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 15364@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{247} 15365@section RM F(7): COBOL Support 15366 15367 15368@quotation 15369 15370"If COBOL (respectively, C) is widely supported in the target 15371environment, implementations supporting the Information Systems Annex 15372should provide the child package @code{Interfaces.COBOL} (respectively, 15373@code{Interfaces.C}) specified in Annex B and should support a 15374@code{convention_identifier} of COBOL (respectively, C) in the interfacing 15375pragmas (see Annex B), thus allowing Ada programs to interface with 15376programs written in that language." 15377@end quotation 15378 15379Followed. 15380 15381@geindex Decimal radix support 15382 15383@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 15384@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{248} 15385@section RM F.1(2): Decimal Radix Support 15386 15387 15388@quotation 15389 15390"Packed decimal should be used as the internal representation for objects 15391of subtype @code{S} when @code{S}'Machine_Radix = 10." 15392@end quotation 15393 15394Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary 15395representations. 15396 15397@geindex Numerics 15398 15399@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 15400@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{249} 15401@section RM G: Numerics 15402 15403 15404@quotation 15405 15406"If Fortran (respectively, C) is widely supported in the target 15407environment, implementations supporting the Numerics Annex 15408should provide the child package @code{Interfaces.Fortran} (respectively, 15409@code{Interfaces.C}) specified in Annex B and should support a 15410@code{convention_identifier} of Fortran (respectively, C) in the interfacing 15411pragmas (see Annex B), thus allowing Ada programs to interface with 15412programs written in that language." 15413@end quotation 15414 15415Followed. 15416 15417@geindex Complex types 15418 15419@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15420@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{24a} 15421@section RM G.1.1(56-58): Complex Types 15422 15423 15424@quotation 15425 15426"Because the usual mathematical meaning of multiplication of a complex 15427operand and a real operand is that of the scaling of both components of 15428the former by the latter, an implementation should not perform this 15429operation by first promoting the real operand to complex type and then 15430performing a full complex multiplication. In systems that, in the 15431future, support an Ada binding to IEC 559:1989, the latter technique 15432will not generate the required result when one of the components of the 15433complex operand is infinite. (Explicit multiplication of the infinite 15434component by the zero component obtained during promotion yields a NaN 15435that propagates into the final result.) Analogous advice applies in the 15436case of multiplication of a complex operand and a pure-imaginary 15437operand, and in the case of division of a complex operand by a real or 15438pure-imaginary operand." 15439@end quotation 15440 15441Not followed. 15442 15443@quotation 15444 15445"Similarly, because the usual mathematical meaning of addition of a 15446complex operand and a real operand is that the imaginary operand remains 15447unchanged, an implementation should not perform this operation by first 15448promoting the real operand to complex type and then performing a full 15449complex addition. In implementations in which the @code{Signed_Zeros} 15450attribute of the component type is @code{True} (and which therefore 15451conform to IEC 559:1989 in regard to the handling of the sign of zero in 15452predefined arithmetic operations), the latter technique will not 15453generate the required result when the imaginary component of the complex 15454operand is a negatively signed zero. (Explicit addition of the negative 15455zero to the zero obtained during promotion yields a positive zero.) 15456Analogous advice applies in the case of addition of a complex operand 15457and a pure-imaginary operand, and in the case of subtraction of a 15458complex operand and a real or pure-imaginary operand." 15459@end quotation 15460 15461Not followed. 15462 15463@quotation 15464 15465"Implementations in which @code{Real'Signed_Zeros} is @code{True} should 15466attempt to provide a rational treatment of the signs of zero results and 15467result components. As one example, the result of the @code{Argument} 15468function should have the sign of the imaginary component of the 15469parameter @code{X} when the point represented by that parameter lies on 15470the positive real axis; as another, the sign of the imaginary component 15471of the @code{Compose_From_Polar} function should be the same as 15472(respectively, the opposite of) that of the @code{Argument} parameter when that 15473parameter has a value of zero and the @code{Modulus} parameter has a 15474nonnegative (respectively, negative) value." 15475@end quotation 15476 15477Followed. 15478 15479@geindex Complex elementary functions 15480 15481@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 15482@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{24b} 15483@section RM G.1.2(49): Complex Elementary Functions 15484 15485 15486@quotation 15487 15488"Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 15489@code{True} should attempt to provide a rational treatment of the signs 15490of zero results and result components. For example, many of the complex 15491elementary functions have components that are odd functions of one of 15492the parameter components; in these cases, the result component should 15493have the sign of the parameter component at the origin. Other complex 15494elementary functions have zero components whose sign is opposite that of 15495a parameter component at the origin, or is always positive or always 15496negative." 15497@end quotation 15498 15499Followed. 15500 15501@geindex Accuracy requirements 15502 15503@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 15504@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{24c} 15505@section RM G.2.4(19): Accuracy Requirements 15506 15507 15508@quotation 15509 15510"The versions of the forward trigonometric functions without a 15511@code{Cycle} parameter should not be implemented by calling the 15512corresponding version with a @code{Cycle} parameter of 15513@code{2.0*Numerics.Pi}, since this will not provide the required 15514accuracy in some portions of the domain. For the same reason, the 15515version of @code{Log} without a @code{Base} parameter should not be 15516implemented by calling the corresponding version with a @code{Base} 15517parameter of @code{Numerics.e}." 15518@end quotation 15519 15520Followed. 15521 15522@geindex Complex arithmetic accuracy 15523 15524@geindex Accuracy 15525@geindex complex arithmetic 15526 15527@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 15528@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{24d} 15529@section RM G.2.6(15): Complex Arithmetic Accuracy 15530 15531 15532@quotation 15533 15534"The version of the @code{Compose_From_Polar} function without a 15535@code{Cycle} parameter should not be implemented by calling the 15536corresponding version with a @code{Cycle} parameter of 15537@code{2.0*Numerics.Pi}, since this will not provide the required 15538accuracy in some portions of the domain." 15539@end quotation 15540 15541Followed. 15542 15543@geindex Sequential elaboration policy 15544 15545@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15546@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{24e} 15547@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15548 15549 15550@quotation 15551 15552"If the partition elaboration policy is @code{Sequential} and the 15553Environment task becomes permanently blocked during elaboration then the 15554partition is deadlocked and it is recommended that the partition be 15555immediately terminated." 15556@end quotation 15557 15558Not followed. 15559 15560@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15561@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{24f}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{250} 15562@chapter Implementation Defined Characteristics 15563 15564 15565In addition to the implementation dependent pragmas and attributes, and the 15566implementation advice, there are a number of other Ada features that are 15567potentially implementation dependent and are designated as 15568implementation-defined. These are mentioned throughout the Ada Reference 15569Manual, and are summarized in Annex M. 15570 15571A requirement for conforming Ada compilers is that they provide 15572documentation describing how the implementation deals with each of these 15573issues. In this chapter you will find each point in Annex M listed, 15574followed by a description of how GNAT 15575handles the implementation dependence. 15576 15577You can use this chapter as a guide to minimizing implementation 15578dependent features in your programs if portability to other compilers 15579and other operating systems is an important consideration. The numbers 15580in each entry below correspond to the paragraph numbers in the Ada 15581Reference Manual. 15582 15583 15584@itemize * 15585 15586@item 15587"Whether or not each recommendation given in Implementation 15588Advice is followed. See 1.1.2(37)." 15589@end itemize 15590 15591See @ref{a,,Implementation Advice}. 15592 15593 15594@itemize * 15595 15596@item 15597"Capacity limitations of the implementation. See 1.1.3(3)." 15598@end itemize 15599 15600The complexity of programs that can be processed is limited only by the 15601total amount of available virtual memory, and disk space for the 15602generated object files. 15603 15604 15605@itemize * 15606 15607@item 15608"Variations from the standard that are impractical to avoid 15609given the implementation's execution environment. See 1.1.3(6)." 15610@end itemize 15611 15612There are no variations from the standard. 15613 15614 15615@itemize * 15616 15617@item 15618"Which code_statements cause external 15619interactions. See 1.1.3(10)." 15620@end itemize 15621 15622Any @emph{code_statement} can potentially cause external interactions. 15623 15624 15625@itemize * 15626 15627@item 15628"The coded representation for the text of an Ada 15629program. See 2.1(4)." 15630@end itemize 15631 15632See separate section on source representation. 15633 15634 15635@itemize * 15636 15637@item 15638"The control functions allowed in comments. See 2.1(14)." 15639@end itemize 15640 15641See separate section on source representation. 15642 15643 15644@itemize * 15645 15646@item 15647"The representation for an end of line. See 2.2(2)." 15648@end itemize 15649 15650See separate section on source representation. 15651 15652 15653@itemize * 15654 15655@item 15656"Maximum supported line length and lexical element 15657length. See 2.2(15)." 15658@end itemize 15659 15660The maximum line length is 255 characters and the maximum length of 15661a lexical element is also 255 characters. This is the default setting 15662if not overridden by the use of compiler switch @emph{-gnaty} (which 15663sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15664line length to be specified to be any value up to 32767. The maximum 15665length of a lexical element is the same as the maximum line length. 15666 15667 15668@itemize * 15669 15670@item 15671"Implementation defined pragmas. See 2.8(14)." 15672@end itemize 15673 15674See @ref{7,,Implementation Defined Pragmas}. 15675 15676 15677@itemize * 15678 15679@item 15680"Effect of pragma @code{Optimize}. See 2.8(27)." 15681@end itemize 15682 15683Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 15684parameter, checks that the optimization flag is set, and aborts if it is 15685not. 15686 15687 15688@itemize * 15689 15690@item 15691"The sequence of characters of the value returned by 15692@code{S'Image} when some of the graphic characters of 15693@code{S'Wide_Image} are not defined in @code{Character}. See 156943.5(37)." 15695@end itemize 15696 15697The sequence of characters is as defined by the wide character encoding 15698method used for the source. See section on source representation for 15699further details. 15700 15701 15702@itemize * 15703 15704@item 15705"The predefined integer types declared in 15706@code{Standard}. See 3.5.4(25)." 15707@end itemize 15708 15709 15710@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15711@headitem 15712 15713Type 15714 15715@tab 15716 15717Representation 15718 15719@item 15720 15721@emph{Short_Short_Integer} 15722 15723@tab 15724 157258 bit signed 15726 15727@item 15728 15729@emph{Short_Integer} 15730 15731@tab 15732 15733(Short) 16 bit signed 15734 15735@item 15736 15737@emph{Integer} 15738 15739@tab 15740 1574132 bit signed 15742 15743@item 15744 15745@emph{Long_Integer} 15746 15747@tab 15748 1574964 bit signed (on most 64 bit targets, 15750depending on the C definition of long). 1575132 bit signed (all other targets) 15752 15753@item 15754 15755@emph{Long_Long_Integer} 15756 15757@tab 15758 1575964 bit signed 15760 15761@end multitable 15762 15763 15764 15765@itemize * 15766 15767@item 15768"Any nonstandard integer types and the operators defined 15769for them. See 3.5.4(26)." 15770@end itemize 15771 15772There are no nonstandard integer types. 15773 15774 15775@itemize * 15776 15777@item 15778"Any nonstandard real types and the operators defined for 15779them. See 3.5.6(8)." 15780@end itemize 15781 15782There are no nonstandard real types. 15783 15784 15785@itemize * 15786 15787@item 15788"What combinations of requested decimal precision and range 15789are supported for floating point types. See 3.5.7(7)." 15790@end itemize 15791 15792The precision and range is as defined by the IEEE standard. 15793 15794 15795@itemize * 15796 15797@item 15798"The predefined floating point types declared in 15799@code{Standard}. See 3.5.7(16)." 15800@end itemize 15801 15802 15803@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15804@headitem 15805 15806Type 15807 15808@tab 15809 15810Representation 15811 15812@item 15813 15814@emph{Short_Float} 15815 15816@tab 15817 1581832 bit IEEE short 15819 15820@item 15821 15822@emph{Float} 15823 15824@tab 15825 15826(Short) 32 bit IEEE short 15827 15828@item 15829 15830@emph{Long_Float} 15831 15832@tab 15833 1583464 bit IEEE long 15835 15836@item 15837 15838@emph{Long_Long_Float} 15839 15840@tab 15841 1584264 bit IEEE long (80 bit IEEE long on x86 processors) 15843 15844@end multitable 15845 15846 15847 15848@itemize * 15849 15850@item 15851"The small of an ordinary fixed point type. See 3.5.9(8)." 15852@end itemize 15853 15854@code{Fine_Delta} is 2**(-63) 15855 15856 15857@itemize * 15858 15859@item 15860"What combinations of small, range, and digits are 15861supported for fixed point types. See 3.5.9(10)." 15862@end itemize 15863 15864Any combinations are permitted that do not result in a small less than 15865@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 15866If the mantissa is larger than 53 bits on machines where Long_Long_Float 15867is 64 bits (true of all architectures except ia32), then the output from 15868Text_IO is accurate to only 53 bits, rather than the full mantissa. This 15869is because floating-point conversions are used to convert fixed point. 15870 15871 15872@itemize * 15873 15874@item 15875"The result of @code{Tags.Expanded_Name} for types declared 15876within an unnamed @emph{block_statement}. See 3.9(10)." 15877@end itemize 15878 15879Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a 15880decimal integer are allocated. 15881 15882 15883@itemize * 15884 15885@item 15886"Implementation-defined attributes. See 4.1.4(12)." 15887@end itemize 15888 15889See @ref{8,,Implementation Defined Attributes}. 15890 15891 15892@itemize * 15893 15894@item 15895"Any implementation-defined time types. See 9.6(6)." 15896@end itemize 15897 15898There are no implementation-defined time types. 15899 15900 15901@itemize * 15902 15903@item 15904"The time base associated with relative delays." 15905@end itemize 15906 15907See 9.6(20). The time base used is that provided by the C library 15908function @code{gettimeofday}. 15909 15910 15911@itemize * 15912 15913@item 15914"The time base of the type @code{Calendar.Time}. See 159159.6(23)." 15916@end itemize 15917 15918The time base used is that provided by the C library function 15919@code{gettimeofday}. 15920 15921 15922@itemize * 15923 15924@item 15925"The time zone used for package @code{Calendar} 15926operations. See 9.6(24)." 15927@end itemize 15928 15929The time zone used by package @code{Calendar} is the current system time zone 15930setting for local time, as accessed by the C library function 15931@code{localtime}. 15932 15933 15934@itemize * 15935 15936@item 15937"Any limit on @emph{delay_until_statements} of 15938@emph{select_statements}. See 9.6(29)." 15939@end itemize 15940 15941There are no such limits. 15942 15943 15944@itemize * 15945 15946@item 15947"Whether or not two non-overlapping parts of a composite 15948object are independently addressable, in the case where packing, record 15949layout, or @code{Component_Size} is specified for the object. See 159509.10(1)." 15951@end itemize 15952 15953Separate components are independently addressable if they do not share 15954overlapping storage units. 15955 15956 15957@itemize * 15958 15959@item 15960"The representation for a compilation. See 10.1(2)." 15961@end itemize 15962 15963A compilation is represented by a sequence of files presented to the 15964compiler in a single invocation of the @emph{gcc} command. 15965 15966 15967@itemize * 15968 15969@item 15970"Any restrictions on compilations that contain multiple 15971compilation_units. See 10.1(4)." 15972@end itemize 15973 15974No single file can contain more than one compilation unit, but any 15975sequence of files can be presented to the compiler as a single 15976compilation. 15977 15978 15979@itemize * 15980 15981@item 15982"The mechanisms for creating an environment and for adding 15983and replacing compilation units. See 10.1.4(3)." 15984@end itemize 15985 15986See separate section on compilation model. 15987 15988 15989@itemize * 15990 15991@item 15992"The manner of explicitly assigning library units to a 15993partition. See 10.2(2)." 15994@end itemize 15995 15996If a unit contains an Ada main program, then the Ada units for the partition 15997are determined by recursive application of the rules in the Ada Reference 15998Manual section 10.2(2-6). In other words, the Ada units will be those that 15999are needed by the main program, and then this definition of need is applied 16000recursively to those units, and the partition contains the transitive 16001closure determined by this relationship. In short, all the necessary units 16002are included, with no need to explicitly specify the list. If additional 16003units are required, e.g., by foreign language units, then all units must be 16004mentioned in the context clause of one of the needed Ada units. 16005 16006If the partition contains no main program, or if the main program is in 16007a language other than Ada, then GNAT 16008provides the binder options @emph{-z} and @emph{-n} respectively, and in 16009this case a list of units can be explicitly supplied to the binder for 16010inclusion in the partition (all units needed by these units will also 16011be included automatically). For full details on the use of these 16012options, refer to @emph{GNAT Make Program gnatmake} in the 16013@cite{GNAT User's Guide}. 16014 16015 16016@itemize * 16017 16018@item 16019"The implementation-defined means, if any, of specifying 16020which compilation units are needed by a given compilation unit. See 1602110.2(2)." 16022@end itemize 16023 16024The units needed by a given compilation unit are as defined in 16025the Ada Reference Manual section 10.2(2-6). There are no 16026implementation-defined pragmas or other implementation-defined 16027means for specifying needed units. 16028 16029 16030@itemize * 16031 16032@item 16033"The manner of designating the main subprogram of a 16034partition. See 10.2(7)." 16035@end itemize 16036 16037The main program is designated by providing the name of the 16038corresponding @code{ALI} file as the input parameter to the binder. 16039 16040 16041@itemize * 16042 16043@item 16044"The order of elaboration of @emph{library_items}. See 1604510.2(18)." 16046@end itemize 16047 16048The first constraint on ordering is that it meets the requirements of 16049Chapter 10 of the Ada Reference Manual. This still leaves some 16050implementation dependent choices, which are resolved by first 16051elaborating bodies as early as possible (i.e., in preference to specs 16052where there is a choice), and second by evaluating the immediate with 16053clauses of a unit to determine the probably best choice, and 16054third by elaborating in alphabetical order of unit names 16055where a choice still remains. 16056 16057 16058@itemize * 16059 16060@item 16061"Parameter passing and function return for the main 16062subprogram. See 10.2(21)." 16063@end itemize 16064 16065The main program has no parameters. It may be a procedure, or a function 16066returning an integer type. In the latter case, the returned integer 16067value is the return code of the program (overriding any value that 16068may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 16069 16070 16071@itemize * 16072 16073@item 16074"The mechanisms for building and running partitions. See 1607510.2(24)." 16076@end itemize 16077 16078GNAT itself supports programs with only a single partition. The GNATDIST 16079tool provided with the GLADE package (which also includes an implementation 16080of the PCS) provides a completely flexible method for building and running 16081programs consisting of multiple partitions. See the separate GLADE manual 16082for details. 16083 16084 16085@itemize * 16086 16087@item 16088"The details of program execution, including program 16089termination. See 10.2(25)." 16090@end itemize 16091 16092See separate section on compilation model. 16093 16094 16095@itemize * 16096 16097@item 16098"The semantics of any non-active partitions supported by the 16099implementation. See 10.2(28)." 16100@end itemize 16101 16102Passive partitions are supported on targets where shared memory is 16103provided by the operating system. See the GLADE reference manual for 16104further details. 16105 16106 16107@itemize * 16108 16109@item 16110"The information returned by @code{Exception_Message}. See 1611111.4.1(10)." 16112@end itemize 16113 16114Exception message returns the null string unless a specific message has 16115been passed by the program. 16116 16117 16118@itemize * 16119 16120@item 16121"The result of @code{Exceptions.Exception_Name} for types 16122declared within an unnamed @emph{block_statement}. See 11.4.1(12)." 16123@end itemize 16124 16125Blocks have implementation defined names of the form @code{B@emph{nnn}} 16126where @emph{nnn} is an integer. 16127 16128 16129@itemize * 16130 16131@item 16132"The information returned by 16133@code{Exception_Information}. See 11.4.1(13)." 16134@end itemize 16135 16136@code{Exception_Information} returns a string in the following format: 16137 16138@example 16139*Exception_Name:* nnnnn 16140*Message:* mmmmm 16141*PID:* ppp 16142*Load address:* 0xhhhh 16143*Call stack traceback locations:* 161440xhhhh 0xhhhh 0xhhhh ... 0xhhh 16145@end example 16146 16147where 16148 16149@quotation 16150 16151 16152@itemize * 16153 16154@item 16155@code{nnnn} is the fully qualified name of the exception in all upper 16156case letters. This line is always present. 16157 16158@item 16159@code{mmmm} is the message (this line present only if message is non-null) 16160 16161@item 16162@code{ppp} is the Process Id value as a decimal integer (this line is 16163present only if the Process Id is nonzero). Currently we are 16164not making use of this field. 16165 16166@item 16167The Load address line, the Call stack traceback locations line and the 16168following values are present only if at least one traceback location was 16169recorded. The Load address indicates the address at which the main executable 16170was loaded; this line may not be present if operating system hasn't relocated 16171the main executable. The values are given in C style format, with lower case 16172letters for a-f, and only as many digits present as are necessary. 16173The line terminator sequence at the end of each line, including 16174the last line is a single @code{LF} character (@code{16#0A#}). 16175@end itemize 16176@end quotation 16177 16178 16179@itemize * 16180 16181@item 16182"Implementation-defined check names. See 11.5(27)." 16183@end itemize 16184 16185The implementation defined check names include Alignment_Check, 16186Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 16187Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 16188program can add implementation-defined check names by means of the pragma 16189Check_Name. See the description of pragma @code{Suppress} for full details. 16190 16191 16192@itemize * 16193 16194@item 16195"The interpretation of each aspect of representation. See 1619613.1(20)." 16197@end itemize 16198 16199See separate section on data representations. 16200 16201 16202@itemize * 16203 16204@item 16205"Any restrictions placed upon representation items. See 1620613.1(20)." 16207@end itemize 16208 16209See separate section on data representations. 16210 16211 16212@itemize * 16213 16214@item 16215"The meaning of @code{Size} for indefinite subtypes. See 1621613.3(48)." 16217@end itemize 16218 16219Size for an indefinite subtype is the maximum possible size, except that 16220for the case of a subprogram parameter, the size of the parameter object 16221is the actual size. 16222 16223 16224@itemize * 16225 16226@item 16227"The default external representation for a type tag. See 1622813.3(75)." 16229@end itemize 16230 16231The default external representation for a type tag is the fully expanded 16232name of the type in upper case letters. 16233 16234 16235@itemize * 16236 16237@item 16238"What determines whether a compilation unit is the same in 16239two different partitions. See 13.3(76)." 16240@end itemize 16241 16242A compilation unit is the same in two different partitions if and only 16243if it derives from the same source file. 16244 16245 16246@itemize * 16247 16248@item 16249"Implementation-defined components. See 13.5.1(15)." 16250@end itemize 16251 16252The only implementation defined component is the tag for a tagged type, 16253which contains a pointer to the dispatching table. 16254 16255 16256@itemize * 16257 16258@item 16259"If @code{Word_Size} = @code{Storage_Unit}, the default bit 16260ordering. See 13.5.3(5)." 16261@end itemize 16262 16263@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 16264implementation, so no non-default bit ordering is supported. The default 16265bit ordering corresponds to the natural endianness of the target architecture. 16266 16267 16268@itemize * 16269 16270@item 16271"The contents of the visible part of package @code{System} 16272and its language-defined children. See 13.7(2)." 16273@end itemize 16274 16275See the definition of these packages in files @code{system.ads} and 16276@code{s-stoele.ads}. Note that two declarations are added to package 16277System. 16278 16279@example 16280Max_Priority : constant Positive := Priority'Last; 16281Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 16282@end example 16283 16284 16285@itemize * 16286 16287@item 16288"The contents of the visible part of package 16289@code{System.Machine_Code}, and the meaning of 16290@emph{code_statements}. See 13.8(7)." 16291@end itemize 16292 16293See the definition and documentation in file @code{s-maccod.ads}. 16294 16295 16296@itemize * 16297 16298@item 16299"The effect of unchecked conversion. See 13.9(11)." 16300@end itemize 16301 16302Unchecked conversion between types of the same size 16303results in an uninterpreted transmission of the bits from one type 16304to the other. If the types are of unequal sizes, then in the case of 16305discrete types, a shorter source is first zero or sign extended as 16306necessary, and a shorter target is simply truncated on the left. 16307For all non-discrete types, the source is first copied if necessary 16308to ensure that the alignment requirements of the target are met, then 16309a pointer is constructed to the source value, and the result is obtained 16310by dereferencing this pointer after converting it to be a pointer to the 16311target type. Unchecked conversions where the target subtype is an 16312unconstrained array are not permitted. If the target alignment is 16313greater than the source alignment, then a copy of the result is 16314made with appropriate alignment 16315 16316 16317@itemize * 16318 16319@item 16320"The semantics of operations on invalid representations. 16321See 13.9.2(10-11)." 16322@end itemize 16323 16324For assignments and other operations where the use of invalid values cannot 16325result in erroneous behavior, the compiler ignores the possibility of invalid 16326values. An exception is raised at the point where an invalid value would 16327result in erroneous behavior. For example executing: 16328 16329@example 16330procedure invalidvals is 16331 X : Integer := -1; 16332 Y : Natural range 1 .. 10; 16333 for Y'Address use X'Address; 16334 Z : Natural range 1 .. 10; 16335 A : array (Natural range 1 .. 10) of Integer; 16336begin 16337 Z := Y; -- no exception 16338 A (Z) := 3; -- exception raised; 16339end; 16340@end example 16341 16342As indicated, an exception is raised on the array assignment, but not 16343on the simple assignment of the invalid negative value from Y to Z. 16344 16345 16346@itemize * 16347 16348@item 16349"The manner of choosing a storage pool for an access type 16350when @code{Storage_Pool} is not specified for the type. See 13.11(17)." 16351@end itemize 16352 16353There are 3 different standard pools used by the compiler when 16354@code{Storage_Pool} is not specified depending whether the type is local 16355to a subprogram or defined at the library level and whether 16356@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime 16357library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and 16358@code{System.Pool_Local} in files @code{s-poosiz.ads}, 16359@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 16360default pools used. 16361 16362 16363@itemize * 16364 16365@item 16366"Whether or not the implementation provides user-accessible 16367names for the standard pool type(s). See 13.11(17)." 16368@end itemize 16369 16370See documentation in the sources of the run time mentioned in the previous 16371paragraph. All these pools are accessible by means of @cite{with}ing 16372these units. 16373 16374 16375@itemize * 16376 16377@item 16378"The meaning of @code{Storage_Size}. See 13.11(18)." 16379@end itemize 16380 16381@code{Storage_Size} is measured in storage units, and refers to the 16382total space available for an access type collection, or to the primary 16383stack space for a task. 16384 16385 16386@itemize * 16387 16388@item 16389"Implementation-defined aspects of storage pools. See 1639013.11(22)." 16391@end itemize 16392 16393See documentation in the sources of the run time mentioned in the 16394paragraph about standard storage pools above 16395for details on GNAT-defined aspects of storage pools. 16396 16397 16398@itemize * 16399 16400@item 16401"The set of restrictions allowed in a pragma 16402@code{Restrictions}. See 13.12(7)." 16403@end itemize 16404 16405See @ref{9,,Standard and Implementation Defined Restrictions}. 16406 16407 16408@itemize * 16409 16410@item 16411"The consequences of violating limitations on 16412@code{Restrictions} pragmas. See 13.12(9)." 16413@end itemize 16414 16415Restrictions that can be checked at compile time result in illegalities 16416if violated. Currently there are no other consequences of violating 16417restrictions. 16418 16419 16420@itemize * 16421 16422@item 16423"The representation used by the @code{Read} and 16424@code{Write} attributes of elementary types in terms of stream 16425elements. See 13.13.2(9)." 16426@end itemize 16427 16428The representation is the in-memory representation of the base type of 16429the type, using the number of bits corresponding to the 16430@code{type'Size} value, and the natural ordering of the machine. 16431 16432 16433@itemize * 16434 16435@item 16436"The names and characteristics of the numeric subtypes 16437declared in the visible part of package @code{Standard}. See A.1(3)." 16438@end itemize 16439 16440See items describing the integer and floating-point types supported. 16441 16442 16443@itemize * 16444 16445@item 16446"The string returned by @code{Character_Set_Version}. 16447See A.3.5(3)." 16448@end itemize 16449 16450@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns 16451the string "Unicode 4.0", referring to version 4.0 of the 16452Unicode specification. 16453 16454 16455@itemize * 16456 16457@item 16458"The accuracy actually achieved by the elementary 16459functions. See A.5.1(1)." 16460@end itemize 16461 16462The elementary functions correspond to the functions available in the C 16463library. Only fast math mode is implemented. 16464 16465 16466@itemize * 16467 16468@item 16469"The sign of a zero result from some of the operators or 16470functions in @code{Numerics.Generic_Elementary_Functions}, when 16471@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)." 16472@end itemize 16473 16474The sign of zeroes follows the requirements of the IEEE 754 standard on 16475floating-point. 16476 16477 16478@itemize * 16479 16480@item 16481"The value of 16482@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)." 16483@end itemize 16484 16485Maximum image width is 6864, see library file @code{s-rannum.ads}. 16486 16487 16488@itemize * 16489 16490@item 16491"The value of 16492@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)." 16493@end itemize 16494 16495Maximum image width is 6864, see library file @code{s-rannum.ads}. 16496 16497 16498@itemize * 16499 16500@item 16501"The algorithms for random number generation. See 16502A.5.2(32)." 16503@end itemize 16504 16505The algorithm is the Mersenne Twister, as documented in the source file 16506@code{s-rannum.adb}. This version of the algorithm has a period of 165072**19937-1. 16508 16509 16510@itemize * 16511 16512@item 16513"The string representation of a random number generator's 16514state. See A.5.2(38)." 16515@end itemize 16516 16517The value returned by the Image function is the concatenation of 16518the fixed-width decimal representations of the 624 32-bit integers 16519of the state vector. 16520 16521 16522@itemize * 16523 16524@item 16525"The minimum time interval between calls to the 16526time-dependent Reset procedure that are guaranteed to initiate different 16527random number sequences. See A.5.2(45)." 16528@end itemize 16529 16530The minimum period between reset calls to guarantee distinct series of 16531random numbers is one microsecond. 16532 16533 16534@itemize * 16535 16536@item 16537"The values of the @code{Model_Mantissa}, 16538@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 16539@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 16540Annex is not supported. See A.5.3(72)." 16541@end itemize 16542 16543Run the compiler with @emph{-gnatS} to produce a listing of package 16544@code{Standard}, has the values of all numeric attributes. 16545 16546 16547@itemize * 16548 16549@item 16550"Any implementation-defined characteristics of the 16551input-output packages. See A.7(14)." 16552@end itemize 16553 16554There are no special implementation defined characteristics for these 16555packages. 16556 16557 16558@itemize * 16559 16560@item 16561"The value of @code{Buffer_Size} in @code{Storage_IO}. See 16562A.9(10)." 16563@end itemize 16564 16565All type representations are contiguous, and the @code{Buffer_Size} is 16566the value of @code{type'Size} rounded up to the next storage unit 16567boundary. 16568 16569 16570@itemize * 16571 16572@item 16573"External files for standard input, standard output, and 16574standard error See A.10(5)." 16575@end itemize 16576 16577These files are mapped onto the files provided by the C streams 16578libraries. See source file @code{i-cstrea.ads} for further details. 16579 16580 16581@itemize * 16582 16583@item 16584"The accuracy of the value produced by @code{Put}. See 16585A.10.9(36)." 16586@end itemize 16587 16588If more digits are requested in the output than are represented by the 16589precision of the value, zeroes are output in the corresponding least 16590significant digit positions. 16591 16592 16593@itemize * 16594 16595@item 16596"The meaning of @code{Argument_Count}, @code{Argument}, and 16597@code{Command_Name}. See A.15(1)." 16598@end itemize 16599 16600These are mapped onto the @code{argv} and @code{argc} parameters of the 16601main program in the natural manner. 16602 16603 16604@itemize * 16605 16606@item 16607"The interpretation of the @code{Form} parameter in procedure 16608@code{Create_Directory}. See A.16(56)." 16609@end itemize 16610 16611The @code{Form} parameter is not used. 16612 16613 16614@itemize * 16615 16616@item 16617"The interpretation of the @code{Form} parameter in procedure 16618@code{Create_Path}. See A.16(60)." 16619@end itemize 16620 16621The @code{Form} parameter is not used. 16622 16623 16624@itemize * 16625 16626@item 16627"The interpretation of the @code{Form} parameter in procedure 16628@code{Copy_File}. See A.16(68)." 16629@end itemize 16630 16631The @code{Form} parameter is case-insensitive. 16632Two fields are recognized in the @code{Form} parameter: 16633 16634@example 16635*preserve=<value>* 16636*mode=<value>* 16637@end example 16638 16639<value> starts immediately after the character '=' and ends with the 16640character immediately preceding the next comma (',') or with the last 16641character of the parameter. 16642 16643The only possible values for preserve= are: 16644 16645 16646@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16647@headitem 16648 16649Value 16650 16651@tab 16652 16653Meaning 16654 16655@item 16656 16657@emph{no_attributes} 16658 16659@tab 16660 16661Do not try to preserve any file attributes. This is the 16662default if no preserve= is found in Form. 16663 16664@item 16665 16666@emph{all_attributes} 16667 16668@tab 16669 16670Try to preserve all file attributes (timestamps, access rights). 16671 16672@item 16673 16674@emph{timestamps} 16675 16676@tab 16677 16678Preserve the timestamp of the copied file, but not the other 16679file attributes. 16680 16681@end multitable 16682 16683 16684The only possible values for mode= are: 16685 16686 16687@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16688@headitem 16689 16690Value 16691 16692@tab 16693 16694Meaning 16695 16696@item 16697 16698@emph{copy} 16699 16700@tab 16701 16702Only do the copy if the destination file does not already exist. 16703If it already exists, Copy_File fails. 16704 16705@item 16706 16707@emph{overwrite} 16708 16709@tab 16710 16711Copy the file in all cases. Overwrite an already existing destination file. 16712 16713@item 16714 16715@emph{append} 16716 16717@tab 16718 16719Append the original file to the destination file. If the destination file 16720does not exist, the destination file is a copy of the source file. 16721When mode=append, the field preserve=, if it exists, is not taken into account. 16722 16723@end multitable 16724 16725 16726If the Form parameter includes one or both of the fields and the value or 16727values are incorrect, Copy_file fails with Use_Error. 16728 16729Examples of correct Forms: 16730 16731@example 16732Form => "preserve=no_attributes,mode=overwrite" (the default) 16733Form => "mode=append" 16734Form => "mode=copy, preserve=all_attributes" 16735@end example 16736 16737Examples of incorrect Forms: 16738 16739@example 16740Form => "preserve=junk" 16741Form => "mode=internal, preserve=timestamps" 16742@end example 16743 16744 16745@itemize * 16746 16747@item 16748"The interpretation of the @code{Pattern} parameter, when not the null string, 16749in the @code{Start_Search} and @code{Search} procedures. 16750See A.16(104) and A.16(112)." 16751@end itemize 16752 16753When the @code{Pattern} parameter is not the null string, it is interpreted 16754according to the syntax of regular expressions as defined in the 16755@code{GNAT.Regexp} package. 16756 16757See @ref{251,,GNAT.Regexp (g-regexp.ads)}. 16758 16759 16760@itemize * 16761 16762@item 16763"Implementation-defined convention names. See B.1(11)." 16764@end itemize 16765 16766The following convention names are supported 16767 16768 16769@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16770@headitem 16771 16772Convention Name 16773 16774@tab 16775 16776Interpretation 16777 16778@item 16779 16780@emph{Ada} 16781 16782@tab 16783 16784Ada 16785 16786@item 16787 16788@emph{Ada_Pass_By_Copy} 16789 16790@tab 16791 16792Allowed for any types except by-reference types such as limited 16793records. Compatible with convention Ada, but causes any parameters 16794with this convention to be passed by copy. 16795 16796@item 16797 16798@emph{Ada_Pass_By_Reference} 16799 16800@tab 16801 16802Allowed for any types except by-copy types such as scalars. 16803Compatible with convention Ada, but causes any parameters 16804with this convention to be passed by reference. 16805 16806@item 16807 16808@emph{Assembler} 16809 16810@tab 16811 16812Assembly language 16813 16814@item 16815 16816@emph{Asm} 16817 16818@tab 16819 16820Synonym for Assembler 16821 16822@item 16823 16824@emph{Assembly} 16825 16826@tab 16827 16828Synonym for Assembler 16829 16830@item 16831 16832@emph{C} 16833 16834@tab 16835 16836C 16837 16838@item 16839 16840@emph{C_Pass_By_Copy} 16841 16842@tab 16843 16844Allowed only for record types, like C, but also notes that record 16845is to be passed by copy rather than reference. 16846 16847@item 16848 16849@emph{COBOL} 16850 16851@tab 16852 16853COBOL 16854 16855@item 16856 16857@emph{C_Plus_Plus (or CPP)} 16858 16859@tab 16860 16861C++ 16862 16863@item 16864 16865@emph{Default} 16866 16867@tab 16868 16869Treated the same as C 16870 16871@item 16872 16873@emph{External} 16874 16875@tab 16876 16877Treated the same as C 16878 16879@item 16880 16881@emph{Fortran} 16882 16883@tab 16884 16885Fortran 16886 16887@item 16888 16889@emph{Intrinsic} 16890 16891@tab 16892 16893For support of pragma @code{Import} with convention Intrinsic, see 16894separate section on Intrinsic Subprograms. 16895 16896@item 16897 16898@emph{Stdcall} 16899 16900@tab 16901 16902Stdcall (used for Windows implementations only). This convention correspond 16903to the WINAPI (previously called Pascal convention) C/C++ convention under 16904Windows. A routine with this convention cleans the stack before 16905exit. This pragma cannot be applied to a dispatching call. 16906 16907@item 16908 16909@emph{DLL} 16910 16911@tab 16912 16913Synonym for Stdcall 16914 16915@item 16916 16917@emph{Win32} 16918 16919@tab 16920 16921Synonym for Stdcall 16922 16923@item 16924 16925@emph{Stubbed} 16926 16927@tab 16928 16929Stubbed is a special convention used to indicate that the body of the 16930subprogram will be entirely ignored. Any call to the subprogram 16931is converted into a raise of the @code{Program_Error} exception. If a 16932pragma @code{Import} specifies convention @code{stubbed} then no body need 16933be present at all. This convention is useful during development for the 16934inclusion of subprograms whose body has not yet been written. 16935In addition, all otherwise unrecognized convention names are also 16936treated as being synonymous with convention C. In all implementations 16937except for VMS, use of such other names results in a warning. In VMS 16938implementations, these names are accepted silently. 16939 16940@end multitable 16941 16942 16943 16944@itemize * 16945 16946@item 16947"The meaning of link names. See B.1(36)." 16948@end itemize 16949 16950Link names are the actual names used by the linker. 16951 16952 16953@itemize * 16954 16955@item 16956"The manner of choosing link names when neither the link 16957name nor the address of an imported or exported entity is specified. See 16958B.1(36)." 16959@end itemize 16960 16961The default linker name is that which would be assigned by the relevant 16962external language, interpreting the Ada name as being in all lower case 16963letters. 16964 16965 16966@itemize * 16967 16968@item 16969"The effect of pragma @code{Linker_Options}. See B.1(37)." 16970@end itemize 16971 16972The string passed to @code{Linker_Options} is presented uninterpreted as 16973an argument to the link command, unless it contains ASCII.NUL characters. 16974NUL characters if they appear act as argument separators, so for example 16975 16976@example 16977pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 16978@end example 16979 16980causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 16981linker. The order of linker options is preserved for a given unit. The final 16982list of options passed to the linker is in reverse order of the elaboration 16983order. For example, linker options for a body always appear before the options 16984from the corresponding package spec. 16985 16986 16987@itemize * 16988 16989@item 16990"The contents of the visible part of package 16991@code{Interfaces} and its language-defined descendants. See B.2(1)." 16992@end itemize 16993 16994See files with prefix @code{i-} in the distributed library. 16995 16996 16997@itemize * 16998 16999@item 17000"Implementation-defined children of package 17001@code{Interfaces}. The contents of the visible part of package 17002@code{Interfaces}. See B.2(11)." 17003@end itemize 17004 17005See files with prefix @code{i-} in the distributed library. 17006 17007 17008@itemize * 17009 17010@item 17011"The types @code{Floating}, @code{Long_Floating}, 17012@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 17013@code{COBOL_Character}; and the initialization of the variables 17014@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 17015@code{Interfaces.COBOL}. See B.4(50)." 17016@end itemize 17017 17018 17019@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17020@headitem 17021 17022COBOL 17023 17024@tab 17025 17026Ada 17027 17028@item 17029 17030@emph{Floating} 17031 17032@tab 17033 17034Float 17035 17036@item 17037 17038@emph{Long_Floating} 17039 17040@tab 17041 17042(Floating) Long_Float 17043 17044@item 17045 17046@emph{Binary} 17047 17048@tab 17049 17050Integer 17051 17052@item 17053 17054@emph{Long_Binary} 17055 17056@tab 17057 17058Long_Long_Integer 17059 17060@item 17061 17062@emph{Decimal_Element} 17063 17064@tab 17065 17066Character 17067 17068@item 17069 17070@emph{COBOL_Character} 17071 17072@tab 17073 17074Character 17075 17076@end multitable 17077 17078 17079For initialization, see the file @code{i-cobol.ads} in the distributed library. 17080 17081 17082@itemize * 17083 17084@item 17085"Support for access to machine instructions. See C.1(1)." 17086@end itemize 17087 17088See documentation in file @code{s-maccod.ads} in the distributed library. 17089 17090 17091@itemize * 17092 17093@item 17094"Implementation-defined aspects of access to machine 17095operations. See C.1(9)." 17096@end itemize 17097 17098See documentation in file @code{s-maccod.ads} in the distributed library. 17099 17100 17101@itemize * 17102 17103@item 17104"Implementation-defined aspects of interrupts. See C.3(2)." 17105@end itemize 17106 17107Interrupts are mapped to signals or conditions as appropriate. See 17108definition of unit 17109@code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details 17110on the interrupts supported on a particular target. 17111 17112 17113@itemize * 17114 17115@item 17116"Implementation-defined aspects of pre-elaboration. See 17117C.4(13)." 17118@end itemize 17119 17120GNAT does not permit a partition to be restarted without reloading, 17121except under control of the debugger. 17122 17123 17124@itemize * 17125 17126@item 17127"The semantics of pragma @code{Discard_Names}. See C.5(7)." 17128@end itemize 17129 17130Pragma @code{Discard_Names} causes names of enumeration literals to 17131be suppressed. In the presence of this pragma, the Image attribute 17132provides the image of the Pos of the literal, and Value accepts 17133Pos values. 17134 17135 17136@itemize * 17137 17138@item 17139"The result of the @code{Task_Identification.Image} 17140attribute. See C.7.1(7)." 17141@end itemize 17142 17143The result of this attribute is a string that identifies 17144the object or component that denotes a given task. If a variable @code{Var} 17145has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, 17146where the suffix @emph{XXXXXXXX} 17147is the hexadecimal representation of the virtual address of the corresponding 17148task control block. If the variable is an array of tasks, the image of each 17149task will have the form of an indexed component indicating the position of a 17150given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a 17151component of a record, the image of the task will have the form of a selected 17152component. These rules are fully recursive, so that the image of a task that 17153is a subcomponent of a composite object corresponds to the expression that 17154designates this task. 17155 17156If a task is created by an allocator, its image depends on the context. If the 17157allocator is part of an object declaration, the rules described above are used 17158to construct its image, and this image is not affected by subsequent 17159assignments. If the allocator appears within an expression, the image 17160includes only the name of the task type. 17161 17162If the configuration pragma Discard_Names is present, or if the restriction 17163No_Implicit_Heap_Allocation is in effect, the image reduces to 17164the numeric suffix, that is to say the hexadecimal representation of the 17165virtual address of the control block of the task. 17166 17167 17168@itemize * 17169 17170@item 17171"The value of @code{Current_Task} when in a protected entry 17172or interrupt handler. See C.7.1(17)." 17173@end itemize 17174 17175Protected entries or interrupt handlers can be executed by any 17176convenient thread, so the value of @code{Current_Task} is undefined. 17177 17178 17179@itemize * 17180 17181@item 17182"The effect of calling @code{Current_Task} from an entry 17183body or interrupt handler. See C.7.1(19)." 17184@end itemize 17185 17186When GNAT can determine statically that @code{Current_Task} is called directly in 17187the body of an entry (or barrier) then a warning is emitted and @code{Program_Error} 17188is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an 17189entry body or interrupt handler is to return the identification of the task 17190currently executing the code. 17191 17192 17193@itemize * 17194 17195@item 17196"Implementation-defined aspects of 17197@code{Task_Attributes}. See C.7.2(19)." 17198@end itemize 17199 17200There are no implementation-defined aspects of @code{Task_Attributes}. 17201 17202 17203@itemize * 17204 17205@item 17206"Values of all @code{Metrics}. See D(2)." 17207@end itemize 17208 17209The metrics information for GNAT depends on the performance of the 17210underlying operating system. The sources of the run-time for tasking 17211implementation, together with the output from @emph{-gnatG} can be 17212used to determine the exact sequence of operating systems calls made 17213to implement various tasking constructs. Together with appropriate 17214information on the performance of the underlying operating system, 17215on the exact target in use, this information can be used to determine 17216the required metrics. 17217 17218 17219@itemize * 17220 17221@item 17222"The declarations of @code{Any_Priority} and 17223@code{Priority}. See D.1(11)." 17224@end itemize 17225 17226See declarations in file @code{system.ads}. 17227 17228 17229@itemize * 17230 17231@item 17232"Implementation-defined execution resources. See D.1(15)." 17233@end itemize 17234 17235There are no implementation-defined execution resources. 17236 17237 17238@itemize * 17239 17240@item 17241"Whether, on a multiprocessor, a task that is waiting for 17242access to a protected object keeps its processor busy. See D.2.1(3)." 17243@end itemize 17244 17245On a multi-processor, a task that is waiting for access to a protected 17246object does not keep its processor busy. 17247 17248 17249@itemize * 17250 17251@item 17252"The affect of implementation defined execution resources 17253on task dispatching. See D.2.1(9)." 17254@end itemize 17255 17256Tasks map to threads in the threads package used by GNAT. Where possible 17257and appropriate, these threads correspond to native threads of the 17258underlying operating system. 17259 17260 17261@itemize * 17262 17263@item 17264"Implementation-defined @emph{policy_identifiers} allowed 17265in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)." 17266@end itemize 17267 17268There are no implementation-defined policy-identifiers allowed in this 17269pragma. 17270 17271 17272@itemize * 17273 17274@item 17275"Implementation-defined aspects of priority inversion. See 17276D.2.2(16)." 17277@end itemize 17278 17279Execution of a task cannot be preempted by the implementation processing 17280of delay expirations for lower priority tasks. 17281 17282 17283@itemize * 17284 17285@item 17286"Implementation-defined task dispatching. See D.2.2(18)." 17287@end itemize 17288 17289The policy is the same as that of the underlying threads implementation. 17290 17291 17292@itemize * 17293 17294@item 17295"Implementation-defined @emph{policy_identifiers} allowed 17296in a pragma @code{Locking_Policy}. See D.3(4)." 17297@end itemize 17298 17299The two implementation defined policies permitted in GNAT are 17300@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On 17301targets that support the @code{Inheritance_Locking} policy, locking is 17302implemented by inheritance, i.e., the task owning the lock operates 17303at a priority equal to the highest priority of any task currently 17304requesting the lock. On targets that support the 17305@code{Concurrent_Readers_Locking} policy, locking is implemented with a 17306read/write lock allowing multiple protected object functions to enter 17307concurrently. 17308 17309 17310@itemize * 17311 17312@item 17313"Default ceiling priorities. See D.3(10)." 17314@end itemize 17315 17316The ceiling priority of protected objects of the type 17317@code{System.Interrupt_Priority'Last} as described in the Ada 17318Reference Manual D.3(10), 17319 17320 17321@itemize * 17322 17323@item 17324"The ceiling of any protected object used internally by 17325the implementation. See D.3(16)." 17326@end itemize 17327 17328The ceiling priority of internal protected objects is 17329@code{System.Priority'Last}. 17330 17331 17332@itemize * 17333 17334@item 17335"Implementation-defined queuing policies. See D.4(1)." 17336@end itemize 17337 17338There are no implementation-defined queuing policies. 17339 17340 17341@itemize * 17342 17343@item 17344"On a multiprocessor, any conditions that cause the 17345completion of an aborted construct to be delayed later than what is 17346specified for a single processor. See D.6(3)." 17347@end itemize 17348 17349The semantics for abort on a multi-processor is the same as on a single 17350processor, there are no further delays. 17351 17352 17353@itemize * 17354 17355@item 17356"Any operations that implicitly require heap storage 17357allocation. See D.7(8)." 17358@end itemize 17359 17360The only operation that implicitly requires heap storage allocation is 17361task creation. 17362 17363 17364@itemize * 17365 17366@item 17367"What happens when a task terminates in the presence of 17368pragma @code{No_Task_Termination}. See D.7(15)." 17369@end itemize 17370 17371Execution is erroneous in that case. 17372 17373 17374@itemize * 17375 17376@item 17377"Implementation-defined aspects of pragma 17378@code{Restrictions}. See D.7(20)." 17379@end itemize 17380 17381There are no such implementation-defined aspects. 17382 17383 17384@itemize * 17385 17386@item 17387"Implementation-defined aspects of package 17388@code{Real_Time}. See D.8(17)." 17389@end itemize 17390 17391There are no implementation defined aspects of package @code{Real_Time}. 17392 17393 17394@itemize * 17395 17396@item 17397"Implementation-defined aspects of 17398@emph{delay_statements}. See D.9(8)." 17399@end itemize 17400 17401Any difference greater than one microsecond will cause the task to be 17402delayed (see D.9(7)). 17403 17404 17405@itemize * 17406 17407@item 17408"The upper bound on the duration of interrupt blocking 17409caused by the implementation. See D.12(5)." 17410@end itemize 17411 17412The upper bound is determined by the underlying operating system. In 17413no cases is it more than 10 milliseconds. 17414 17415 17416@itemize * 17417 17418@item 17419"The means for creating and executing distributed 17420programs. See E(5)." 17421@end itemize 17422 17423The GLADE package provides a utility GNATDIST for creating and executing 17424distributed programs. See the GLADE reference manual for further details. 17425 17426 17427@itemize * 17428 17429@item 17430"Any events that can result in a partition becoming 17431inaccessible. See E.1(7)." 17432@end itemize 17433 17434See the GLADE reference manual for full details on such events. 17435 17436 17437@itemize * 17438 17439@item 17440"The scheduling policies, treatment of priorities, and 17441management of shared resources between partitions in certain cases. See 17442E.1(11)." 17443@end itemize 17444 17445See the GLADE reference manual for full details on these aspects of 17446multi-partition execution. 17447 17448 17449@itemize * 17450 17451@item 17452"Events that cause the version of a compilation unit to 17453change. See E.3(5)." 17454@end itemize 17455 17456Editing the source file of a compilation unit, or the source files of 17457any units on which it is dependent in a significant way cause the version 17458to change. No other actions cause the version number to change. All changes 17459are significant except those which affect only layout, capitalization or 17460comments. 17461 17462 17463@itemize * 17464 17465@item 17466"Whether the execution of the remote subprogram is 17467immediately aborted as a result of cancellation. See E.4(13)." 17468@end itemize 17469 17470See the GLADE reference manual for details on the effect of abort in 17471a distributed application. 17472 17473 17474@itemize * 17475 17476@item 17477"Implementation-defined aspects of the PCS. See E.5(25)." 17478@end itemize 17479 17480See the GLADE reference manual for a full description of all implementation 17481defined aspects of the PCS. 17482 17483 17484@itemize * 17485 17486@item 17487"Implementation-defined interfaces in the PCS. See 17488E.5(26)." 17489@end itemize 17490 17491See the GLADE reference manual for a full description of all 17492implementation defined interfaces. 17493 17494 17495@itemize * 17496 17497@item 17498"The values of named numbers in the package 17499@code{Decimal}. See F.2(7)." 17500@end itemize 17501 17502 17503@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17504@headitem 17505 17506Named Number 17507 17508@tab 17509 17510Value 17511 17512@item 17513 17514@emph{Max_Scale} 17515 17516@tab 17517 17518+18 17519 17520@item 17521 17522@emph{Min_Scale} 17523 17524@tab 17525 17526-18 17527 17528@item 17529 17530@emph{Min_Delta} 17531 17532@tab 17533 175341.0E-18 17535 17536@item 17537 17538@emph{Max_Delta} 17539 17540@tab 17541 175421.0E+18 17543 17544@item 17545 17546@emph{Max_Decimal_Digits} 17547 17548@tab 17549 1755018 17551 17552@end multitable 17553 17554 17555 17556@itemize * 17557 17558@item 17559"The value of @code{Max_Picture_Length} in the package 17560@code{Text_IO.Editing}. See F.3.3(16)." 17561@end itemize 17562 1756364 17564 17565 17566@itemize * 17567 17568@item 17569"The value of @code{Max_Picture_Length} in the package 17570@code{Wide_Text_IO.Editing}. See F.3.4(5)." 17571@end itemize 17572 1757364 17574 17575 17576@itemize * 17577 17578@item 17579"The accuracy actually achieved by the complex elementary 17580functions and by other complex arithmetic operations. See G.1(1)." 17581@end itemize 17582 17583Standard library functions are used for the complex arithmetic 17584operations. Only fast math mode is currently supported. 17585 17586 17587@itemize * 17588 17589@item 17590"The sign of a zero result (or a component thereof) from 17591any operator or function in @code{Numerics.Generic_Complex_Types}, when 17592@code{Real'Signed_Zeros} is True. See G.1.1(53)." 17593@end itemize 17594 17595The signs of zero values are as recommended by the relevant 17596implementation advice. 17597 17598 17599@itemize * 17600 17601@item 17602"The sign of a zero result (or a component thereof) from 17603any operator or function in 17604@code{Numerics.Generic_Complex_Elementary_Functions}, when 17605@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)." 17606@end itemize 17607 17608The signs of zero values are as recommended by the relevant 17609implementation advice. 17610 17611 17612@itemize * 17613 17614@item 17615"Whether the strict mode or the relaxed mode is the 17616default. See G.2(2)." 17617@end itemize 17618 17619The strict mode is the default. There is no separate relaxed mode. GNAT 17620provides a highly efficient implementation of strict mode. 17621 17622 17623@itemize * 17624 17625@item 17626"The result interval in certain cases of fixed-to-float 17627conversion. See G.2.1(10)." 17628@end itemize 17629 17630For cases where the result interval is implementation dependent, the 17631accuracy is that provided by performing all operations in 64-bit IEEE 17632floating-point format. 17633 17634 17635@itemize * 17636 17637@item 17638"The result of a floating point arithmetic operation in 17639overflow situations, when the @code{Machine_Overflows} attribute of the 17640result type is @code{False}. See G.2.1(13)." 17641@end itemize 17642 17643Infinite and NaN values are produced as dictated by the IEEE 17644floating-point standard. 17645Note that on machines that are not fully compliant with the IEEE 17646floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 17647must be used for achieving IEEE conforming behavior (although at the cost 17648of a significant performance penalty), so infinite and NaN values are 17649properly generated. 17650 17651 17652@itemize * 17653 17654@item 17655"The result interval for division (or exponentiation by a 17656negative exponent), when the floating point hardware implements division 17657as multiplication by a reciprocal. See G.2.1(16)." 17658@end itemize 17659 17660Not relevant, division is IEEE exact. 17661 17662 17663@itemize * 17664 17665@item 17666"The definition of close result set, which determines the 17667accuracy of certain fixed point multiplications and divisions. See 17668G.2.3(5)." 17669@end itemize 17670 17671Operations in the close result set are performed using IEEE long format 17672floating-point arithmetic. The input operands are converted to 17673floating-point, the operation is done in floating-point, and the result 17674is converted to the target type. 17675 17676 17677@itemize * 17678 17679@item 17680"Conditions on a @emph{universal_real} operand of a fixed 17681point multiplication or division for which the result shall be in the 17682perfect result set. See G.2.3(22)." 17683@end itemize 17684 17685The result is only defined to be in the perfect result set if the result 17686can be computed by a single scaling operation involving a scale factor 17687representable in 64-bits. 17688 17689 17690@itemize * 17691 17692@item 17693"The result of a fixed point arithmetic operation in 17694overflow situations, when the @code{Machine_Overflows} attribute of the 17695result type is @code{False}. See G.2.3(27)." 17696@end itemize 17697 17698Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 17699types. 17700 17701 17702@itemize * 17703 17704@item 17705"The result of an elementary function reference in 17706overflow situations, when the @code{Machine_Overflows} attribute of the 17707result type is @code{False}. See G.2.4(4)." 17708@end itemize 17709 17710IEEE infinite and Nan values are produced as appropriate. 17711 17712 17713@itemize * 17714 17715@item 17716"The value of the angle threshold, within which certain 17717elementary functions, complex arithmetic operations, and complex 17718elementary functions yield results conforming to a maximum relative 17719error bound. See G.2.4(10)." 17720@end itemize 17721 17722Information on this subject is not yet available. 17723 17724 17725@itemize * 17726 17727@item 17728"The accuracy of certain elementary functions for 17729parameters beyond the angle threshold. See G.2.4(10)." 17730@end itemize 17731 17732Information on this subject is not yet available. 17733 17734 17735@itemize * 17736 17737@item 17738"The result of a complex arithmetic operation or complex 17739elementary function reference in overflow situations, when the 17740@code{Machine_Overflows} attribute of the corresponding real type is 17741@code{False}. See G.2.6(5)." 17742@end itemize 17743 17744IEEE infinite and Nan values are produced as appropriate. 17745 17746 17747@itemize * 17748 17749@item 17750"The accuracy of certain complex arithmetic operations and 17751certain complex elementary functions for parameters (or components 17752thereof) beyond the angle threshold. See G.2.6(8)." 17753@end itemize 17754 17755Information on those subjects is not yet available. 17756 17757 17758@itemize * 17759 17760@item 17761"Information regarding bounded errors and erroneous 17762execution. See H.2(1)." 17763@end itemize 17764 17765Information on this subject is not yet available. 17766 17767 17768@itemize * 17769 17770@item 17771"Implementation-defined aspects of pragma 17772@code{Inspection_Point}. See H.3.2(8)." 17773@end itemize 17774 17775Pragma @code{Inspection_Point} ensures that the variable is live and can 17776be examined by the debugger at the inspection point. 17777 17778 17779@itemize * 17780 17781@item 17782"Implementation-defined aspects of pragma 17783@code{Restrictions}. See H.4(25)." 17784@end itemize 17785 17786There are no implementation-defined aspects of pragma @code{Restrictions}. The 17787use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 17788generated code. Checks must suppressed by use of pragma @code{Suppress}. 17789 17790 17791@itemize * 17792 17793@item 17794"Any restrictions on pragma @code{Restrictions}. See 17795H.4(27)." 17796@end itemize 17797 17798There are no restrictions on pragma @code{Restrictions}. 17799 17800@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 17801@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{252}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{253} 17802@chapter Intrinsic Subprograms 17803 17804 17805@geindex Intrinsic Subprograms 17806 17807GNAT allows a user application program to write the declaration: 17808 17809@example 17810pragma Import (Intrinsic, name); 17811@end example 17812 17813providing that the name corresponds to one of the implemented intrinsic 17814subprograms in GNAT, and that the parameter profile of the referenced 17815subprogram meets the requirements. This chapter describes the set of 17816implemented intrinsic subprograms, and the requirements on parameter profiles. 17817Note that no body is supplied; as with other uses of pragma Import, the 17818body is supplied elsewhere (in this case by the compiler itself). Note 17819that any use of this feature is potentially non-portable, since the 17820Ada standard does not require Ada compilers to implement this feature. 17821 17822@menu 17823* Intrinsic Operators:: 17824* Compilation_ISO_Date:: 17825* Compilation_Date:: 17826* Compilation_Time:: 17827* Enclosing_Entity:: 17828* Exception_Information:: 17829* Exception_Message:: 17830* Exception_Name:: 17831* File:: 17832* Line:: 17833* Shifts and Rotates:: 17834* Source_Location:: 17835 17836@end menu 17837 17838@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms 17839@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{254}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{255} 17840@section Intrinsic Operators 17841 17842 17843@geindex Intrinsic operator 17844 17845All the predefined numeric operators in package Standard 17846in @code{pragma Import (Intrinsic,..)} 17847declarations. In the binary operator case, the operands must have the same 17848size. The operand or operands must also be appropriate for 17849the operator. For example, for addition, the operands must 17850both be floating-point or both be fixed-point, and the 17851right operand for @code{"**"} must have a root type of 17852@code{Standard.Integer'Base}. 17853You can use an intrinsic operator declaration as in the following example: 17854 17855@example 17856type Int1 is new Integer; 17857type Int2 is new Integer; 17858 17859function "+" (X1 : Int1; X2 : Int2) return Int1; 17860function "+" (X1 : Int1; X2 : Int2) return Int2; 17861pragma Import (Intrinsic, "+"); 17862@end example 17863 17864This declaration would permit 'mixed mode' arithmetic on items 17865of the differing types @code{Int1} and @code{Int2}. 17866It is also possible to specify such operators for private types, if the 17867full views are appropriate arithmetic types. 17868 17869@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms 17870@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{256}@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{257} 17871@section Compilation_ISO_Date 17872 17873 17874@geindex Compilation_ISO_Date 17875 17876This intrinsic subprogram is used in the implementation of the 17877library package @code{GNAT.Source_Info}. The only useful use of the 17878intrinsic import in this case is the one in this unit, so an 17879application program should simply call the function 17880@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of 17881the current compilation (in local time format YYYY-MM-DD). 17882 17883@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms 17884@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{258}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{259} 17885@section Compilation_Date 17886 17887 17888@geindex Compilation_Date 17889 17890Same as Compilation_ISO_Date, except the string is in the form 17891MMM DD YYYY. 17892 17893@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 17894@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{25a}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{25b} 17895@section Compilation_Time 17896 17897 17898@geindex Compilation_Time 17899 17900This intrinsic subprogram is used in the implementation of the 17901library package @code{GNAT.Source_Info}. The only useful use of the 17902intrinsic import in this case is the one in this unit, so an 17903application program should simply call the function 17904@code{GNAT.Source_Info.Compilation_Time} to obtain the time of 17905the current compilation (in local time format HH:MM:SS). 17906 17907@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 17908@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{25c}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{25d} 17909@section Enclosing_Entity 17910 17911 17912@geindex Enclosing_Entity 17913 17914This intrinsic subprogram is used in the implementation of the 17915library package @code{GNAT.Source_Info}. The only useful use of the 17916intrinsic import in this case is the one in this unit, so an 17917application program should simply call the function 17918@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 17919the current subprogram, package, task, entry, or protected subprogram. 17920 17921@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 17922@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{25f} 17923@section Exception_Information 17924 17925 17926@geindex Exception_Information' 17927 17928This intrinsic subprogram is used in the implementation of the 17929library package @code{GNAT.Current_Exception}. The only useful 17930use of the intrinsic import in this case is the one in this unit, 17931so an application program should simply call the function 17932@code{GNAT.Current_Exception.Exception_Information} to obtain 17933the exception information associated with the current exception. 17934 17935@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 17936@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{260}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{261} 17937@section Exception_Message 17938 17939 17940@geindex Exception_Message 17941 17942This intrinsic subprogram is used in the implementation of the 17943library package @code{GNAT.Current_Exception}. The only useful 17944use of the intrinsic import in this case is the one in this unit, 17945so an application program should simply call the function 17946@code{GNAT.Current_Exception.Exception_Message} to obtain 17947the message associated with the current exception. 17948 17949@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 17950@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{262}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{263} 17951@section Exception_Name 17952 17953 17954@geindex Exception_Name 17955 17956This intrinsic subprogram is used in the implementation of the 17957library package @code{GNAT.Current_Exception}. The only useful 17958use of the intrinsic import in this case is the one in this unit, 17959so an application program should simply call the function 17960@code{GNAT.Current_Exception.Exception_Name} to obtain 17961the name of the current exception. 17962 17963@node File,Line,Exception_Name,Intrinsic Subprograms 17964@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{264}@anchor{gnat_rm/intrinsic_subprograms file}@anchor{265} 17965@section File 17966 17967 17968@geindex File 17969 17970This intrinsic subprogram is used in the implementation of the 17971library package @code{GNAT.Source_Info}. The only useful use of the 17972intrinsic import in this case is the one in this unit, so an 17973application program should simply call the function 17974@code{GNAT.Source_Info.File} to obtain the name of the current 17975file. 17976 17977@node Line,Shifts and Rotates,File,Intrinsic Subprograms 17978@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{266}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{267} 17979@section Line 17980 17981 17982@geindex Line 17983 17984This intrinsic subprogram is used in the implementation of the 17985library package @code{GNAT.Source_Info}. The only useful use of the 17986intrinsic import in this case is the one in this unit, so an 17987application program should simply call the function 17988@code{GNAT.Source_Info.Line} to obtain the number of the current 17989source line. 17990 17991@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 17992@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{268}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{269} 17993@section Shifts and Rotates 17994 17995 17996@geindex Shift_Left 17997 17998@geindex Shift_Right 17999 18000@geindex Shift_Right_Arithmetic 18001 18002@geindex Rotate_Left 18003 18004@geindex Rotate_Right 18005 18006In standard Ada, the shift and rotate functions are available only 18007for the predefined modular types in package @code{Interfaces}. However, in 18008GNAT it is possible to define these functions for any integer 18009type (signed or modular), as in this example: 18010 18011@example 18012function Shift_Left 18013 (Value : T; 18014 Amount : Natural) return T; 18015@end example 18016 18017The function name must be one of 18018Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 18019Rotate_Right. T must be an integer type. T'Size must be 180208, 16, 32 or 64 bits; if T is modular, the modulus 18021must be 2**8, 2**16, 2**32 or 2**64. 18022The result type must be the same as the type of @code{Value}. 18023The shift amount must be Natural. 18024The formal parameter names can be anything. 18025 18026A more convenient way of providing these shift operators is to use 18027the Provide_Shift_Operators pragma, which provides the function declarations 18028and corresponding pragma Import's for all five shift functions. 18029 18030@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 18031@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{26b} 18032@section Source_Location 18033 18034 18035@geindex Source_Location 18036 18037This intrinsic subprogram is used in the implementation of the 18038library routine @code{GNAT.Source_Info}. The only useful use of the 18039intrinsic import in this case is the one in this unit, so an 18040application program should simply call the function 18041@code{GNAT.Source_Info.Source_Location} to obtain the current 18042source file location. 18043 18044@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 18045@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{26c}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{26d} 18046@chapter Representation Clauses and Pragmas 18047 18048 18049@geindex Representation Clauses 18050 18051@geindex Representation Clause 18052 18053@geindex Representation Pragma 18054 18055@geindex Pragma 18056@geindex representation 18057 18058This section describes the representation clauses accepted by GNAT, and 18059their effect on the representation of corresponding data objects. 18060 18061GNAT fully implements Annex C (Systems Programming). This means that all 18062the implementation advice sections in chapter 13 are fully implemented. 18063However, these sections only require a minimal level of support for 18064representation clauses. GNAT provides much more extensive capabilities, 18065and this section describes the additional capabilities provided. 18066 18067@menu 18068* Alignment Clauses:: 18069* Size Clauses:: 18070* Storage_Size Clauses:: 18071* Size of Variant Record Objects:: 18072* Biased Representation:: 18073* Value_Size and Object_Size Clauses:: 18074* Component_Size Clauses:: 18075* Bit_Order Clauses:: 18076* Effect of Bit_Order on Byte Ordering:: 18077* Pragma Pack for Arrays:: 18078* Pragma Pack for Records:: 18079* Record Representation Clauses:: 18080* Handling of Records with Holes:: 18081* Enumeration Clauses:: 18082* Address Clauses:: 18083* Use of Address Clauses for Memory-Mapped I/O:: 18084* Effect of Convention on Representation:: 18085* Conventions and Anonymous Access Types:: 18086* Determining the Representations chosen by GNAT:: 18087 18088@end menu 18089 18090@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 18091@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{26e}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{26f} 18092@section Alignment Clauses 18093 18094 18095@geindex Alignment Clause 18096 18097GNAT requires that all alignment clauses specify a power of 2, and all 18098default alignments are always a power of 2. The default alignment 18099values are as follows: 18100 18101 18102@itemize * 18103 18104@item 18105@emph{Elementary Types}. 18106 18107For elementary types, the alignment is the minimum of the actual size of 18108objects of the type divided by @code{Storage_Unit}, 18109and the maximum alignment supported by the target. 18110(This maximum alignment is given by the GNAT-specific attribute 18111@code{Standard'Maximum_Alignment}; see @ref{189,,Attribute Maximum_Alignment}.) 18112 18113@geindex Maximum_Alignment attribute 18114 18115For example, for type @code{Long_Float}, the object size is 8 bytes, and the 18116default alignment will be 8 on any target that supports alignments 18117this large, but on some targets, the maximum alignment may be smaller 18118than 8, in which case objects of type @code{Long_Float} will be maximally 18119aligned. 18120 18121@item 18122@emph{Arrays}. 18123 18124For arrays, the alignment is equal to the alignment of the component type 18125for the normal case where no packing or component size is given. If the 18126array is packed, and the packing is effective (see separate section on 18127packed arrays), then the alignment will be either 4, 2, or 1 for long packed 18128arrays or arrays whose length is not known at compile time, depending on 18129whether the component size is divisible by 4, 2, or is odd. For short packed 18130arrays, which are handled internally as modular types, the alignment 18131will be as described for elementary types, e.g. a packed array of length 1813231 bits will have an object size of four bytes, and an alignment of 4. 18133 18134@item 18135@emph{Records}. 18136 18137For the normal unpacked case, the alignment of a record is equal to 18138the maximum alignment of any of its components. For tagged records, this 18139includes the implicit access type used for the tag. If a pragma @code{Pack} 18140is used and all components are packable (see separate section on pragma 18141@code{Pack}), then the resulting alignment is 1, unless the layout of the 18142record makes it profitable to increase it. 18143 18144A special case is when: 18145 18146 18147@itemize * 18148 18149@item 18150the size of the record is given explicitly, or a 18151full record representation clause is given, and 18152 18153@item 18154the size of the record is 2, 4, or 8 bytes. 18155@end itemize 18156 18157In this case, an alignment is chosen to match the 18158size of the record. For example, if we have: 18159 18160@example 18161type Small is record 18162 A, B : Character; 18163end record; 18164for Small'Size use 16; 18165@end example 18166 18167then the default alignment of the record type @code{Small} is 2, not 1. This 18168leads to more efficient code when the record is treated as a unit, and also 18169allows the type to specified as @code{Atomic} on architectures requiring 18170strict alignment. 18171@end itemize 18172 18173An alignment clause may specify a larger alignment than the default value 18174up to some maximum value dependent on the target (obtainable by using the 18175attribute reference @code{Standard'Maximum_Alignment}). It may also specify 18176a smaller alignment than the default value for enumeration, integer and 18177fixed point types, as well as for record types, for example 18178 18179@example 18180type V is record 18181 A : Integer; 18182end record; 18183 18184for V'alignment use 1; 18185@end example 18186 18187@geindex Alignment 18188@geindex default 18189 18190The default alignment for the type @code{V} is 4, as a result of the 18191Integer field in the record, but it is permissible, as shown, to 18192override the default alignment of the record with a smaller value. 18193 18194@geindex Alignment 18195@geindex subtypes 18196 18197Note that according to the Ada standard, an alignment clause applies only 18198to the first named subtype. If additional subtypes are declared, then the 18199compiler is allowed to choose any alignment it likes, and there is no way 18200to control this choice. Consider: 18201 18202@example 18203type R is range 1 .. 10_000; 18204for R'Alignment use 1; 18205subtype RS is R range 1 .. 1000; 18206@end example 18207 18208The alignment clause specifies an alignment of 1 for the first named subtype 18209@code{R} but this does not necessarily apply to @code{RS}. When writing 18210portable Ada code, you should avoid writing code that explicitly or 18211implicitly relies on the alignment of such subtypes. 18212 18213For the GNAT compiler, if an explicit alignment clause is given, this 18214value is also used for any subsequent subtypes. So for GNAT, in the 18215above example, you can count on the alignment of @code{RS} being 1. But this 18216assumption is non-portable, and other compilers may choose different 18217alignments for the subtype @code{RS}. 18218 18219@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 18220@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{270}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{271} 18221@section Size Clauses 18222 18223 18224@geindex Size Clause 18225 18226The default size for a type @code{T} is obtainable through the 18227language-defined attribute @code{T'Size} and also through the 18228equivalent GNAT-defined attribute @code{T'Value_Size}. 18229For objects of type @code{T}, GNAT will generally increase the type size 18230so that the object size (obtainable through the GNAT-defined attribute 18231@code{T'Object_Size}) 18232is a multiple of @code{T'Alignment * Storage_Unit}. 18233 18234For example: 18235 18236@example 18237type Smallint is range 1 .. 6; 18238 18239type Rec is record 18240 Y1 : integer; 18241 Y2 : boolean; 18242end record; 18243@end example 18244 18245In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 18246as specified by the RM rules, 18247but objects of this type will have a size of 8 18248(@code{Smallint'Object_Size} = 8), 18249since objects by default occupy an integral number 18250of storage units. On some targets, notably older 18251versions of the Digital Alpha, the size of stand 18252alone objects of this type may be 32, reflecting 18253the inability of the hardware to do byte load/stores. 18254 18255Similarly, the size of type @code{Rec} is 40 bits 18256(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 18257the alignment is 4, so objects of this type will have 18258their size increased to 64 bits so that it is a multiple 18259of the alignment (in bits). This decision is 18260in accordance with the specific Implementation Advice in RM 13.3(43): 18261 18262@quotation 18263 18264"A @code{Size} clause should be supported for an object if the specified 18265@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 18266to a size in storage elements that is a multiple of the object's 18267@code{Alignment} (if the @code{Alignment} is nonzero)." 18268@end quotation 18269 18270An explicit size clause may be used to override the default size by 18271increasing it. For example, if we have: 18272 18273@example 18274type My_Boolean is new Boolean; 18275for My_Boolean'Size use 32; 18276@end example 18277 18278then values of this type will always be 32 bits long. In the case of 18279discrete types, the size can be increased up to 64 bits, with the effect 18280that the entire specified field is used to hold the value, sign- or 18281zero-extended as appropriate. If more than 64 bits is specified, then 18282padding space is allocated after the value, and a warning is issued that 18283there are unused bits. 18284 18285Similarly the size of records and arrays may be increased, and the effect 18286is to add padding bits after the value. This also causes a warning message 18287to be generated. 18288 18289The largest Size value permitted in GNAT is 2**31-1. Since this is a 18290Size in bits, this corresponds to an object of size 256 megabytes (minus 18291one). This limitation is true on all targets. The reason for this 18292limitation is that it improves the quality of the code in many cases 18293if it is known that a Size value can be accommodated in an object of 18294type Integer. 18295 18296@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 18297@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{272}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{273} 18298@section Storage_Size Clauses 18299 18300 18301@geindex Storage_Size Clause 18302 18303For tasks, the @code{Storage_Size} clause specifies the amount of space 18304to be allocated for the task stack. This cannot be extended, and if the 18305stack is exhausted, then @code{Storage_Error} will be raised (if stack 18306checking is enabled). Use a @code{Storage_Size} attribute definition clause, 18307or a @code{Storage_Size} pragma in the task definition to set the 18308appropriate required size. A useful technique is to include in every 18309task definition a pragma of the form: 18310 18311@example 18312pragma Storage_Size (Default_Stack_Size); 18313@end example 18314 18315Then @code{Default_Stack_Size} can be defined in a global package, and 18316modified as required. Any tasks requiring stack sizes different from the 18317default can have an appropriate alternative reference in the pragma. 18318 18319You can also use the @emph{-d} binder switch to modify the default stack 18320size. 18321 18322For access types, the @code{Storage_Size} clause specifies the maximum 18323space available for allocation of objects of the type. If this space is 18324exceeded then @code{Storage_Error} will be raised by an allocation attempt. 18325In the case where the access type is declared local to a subprogram, the 18326use of a @code{Storage_Size} clause triggers automatic use of a special 18327predefined storage pool (@code{System.Pool_Size}) that ensures that all 18328space for the pool is automatically reclaimed on exit from the scope in 18329which the type is declared. 18330 18331A special case recognized by the compiler is the specification of a 18332@code{Storage_Size} of zero for an access type. This means that no 18333items can be allocated from the pool, and this is recognized at compile 18334time, and all the overhead normally associated with maintaining a fixed 18335size storage pool is eliminated. Consider the following example: 18336 18337@example 18338procedure p is 18339 type R is array (Natural) of Character; 18340 type P is access all R; 18341 for P'Storage_Size use 0; 18342 -- Above access type intended only for interfacing purposes 18343 18344 y : P; 18345 18346 procedure g (m : P); 18347 pragma Import (C, g); 18348 18349 -- ... 18350 18351begin 18352 -- ... 18353 y := new R; 18354end; 18355@end example 18356 18357As indicated in this example, these dummy storage pools are often useful in 18358connection with interfacing where no object will ever be allocated. If you 18359compile the above example, you get the warning: 18360 18361@example 18362p.adb:16:09: warning: allocation from empty storage pool 18363p.adb:16:09: warning: Storage_Error will be raised at run time 18364@end example 18365 18366Of course in practice, there will not be any explicit allocators in the 18367case of such an access declaration. 18368 18369@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 18370@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{274}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{275} 18371@section Size of Variant Record Objects 18372 18373 18374@geindex Size 18375@geindex variant record objects 18376 18377@geindex Variant record objects 18378@geindex size 18379 18380In the case of variant record objects, there is a question whether Size gives 18381information about a particular variant, or the maximum size required 18382for any variant. Consider the following program 18383 18384@example 18385with Text_IO; use Text_IO; 18386procedure q is 18387 type R1 (A : Boolean := False) is record 18388 case A is 18389 when True => X : Character; 18390 when False => null; 18391 end case; 18392 end record; 18393 18394 V1 : R1 (False); 18395 V2 : R1; 18396 18397begin 18398 Put_Line (Integer'Image (V1'Size)); 18399 Put_Line (Integer'Image (V2'Size)); 18400end q; 18401@end example 18402 18403Here we are dealing with a variant record, where the True variant 18404requires 16 bits, and the False variant requires 8 bits. 18405In the above example, both V1 and V2 contain the False variant, 18406which is only 8 bits long. However, the result of running the 18407program is: 18408 18409@example 184108 1841116 18412@end example 18413 18414The reason for the difference here is that the discriminant value of 18415V1 is fixed, and will always be False. It is not possible to assign 18416a True variant value to V1, therefore 8 bits is sufficient. On the 18417other hand, in the case of V2, the initial discriminant value is 18418False (from the default), but it is possible to assign a True 18419variant value to V2, therefore 16 bits must be allocated for V2 18420in the general case, even fewer bits may be needed at any particular 18421point during the program execution. 18422 18423As can be seen from the output of this program, the @code{'Size} 18424attribute applied to such an object in GNAT gives the actual allocated 18425size of the variable, which is the largest size of any of the variants. 18426The Ada Reference Manual is not completely clear on what choice should 18427be made here, but the GNAT behavior seems most consistent with the 18428language in the RM. 18429 18430In some cases, it may be desirable to obtain the size of the current 18431variant, rather than the size of the largest variant. This can be 18432achieved in GNAT by making use of the fact that in the case of a 18433subprogram parameter, GNAT does indeed return the size of the current 18434variant (because a subprogram has no way of knowing how much space 18435is actually allocated for the actual). 18436 18437Consider the following modified version of the above program: 18438 18439@example 18440with Text_IO; use Text_IO; 18441procedure q is 18442 type R1 (A : Boolean := False) is record 18443 case A is 18444 when True => X : Character; 18445 when False => null; 18446 end case; 18447 end record; 18448 18449 V2 : R1; 18450 18451 function Size (V : R1) return Integer is 18452 begin 18453 return V'Size; 18454 end Size; 18455 18456begin 18457 Put_Line (Integer'Image (V2'Size)); 18458 Put_Line (Integer'Image (Size (V2))); 18459 V2 := (True, 'x'); 18460 Put_Line (Integer'Image (V2'Size)); 18461 Put_Line (Integer'Image (Size (V2))); 18462end q; 18463@end example 18464 18465The output from this program is 18466 18467@example 1846816 184698 1847016 1847116 18472@end example 18473 18474Here we see that while the @code{'Size} attribute always returns 18475the maximum size, regardless of the current variant value, the 18476@code{Size} function does indeed return the size of the current 18477variant value. 18478 18479@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18480@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{276}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{277} 18481@section Biased Representation 18482 18483 18484@geindex Size for biased representation 18485 18486@geindex Biased representation 18487 18488In the case of scalars with a range starting at other than zero, it is 18489possible in some cases to specify a size smaller than the default minimum 18490value, and in such cases, GNAT uses an unsigned biased representation, 18491in which zero is used to represent the lower bound, and successive values 18492represent successive values of the type. 18493 18494For example, suppose we have the declaration: 18495 18496@example 18497type Small is range -7 .. -4; 18498for Small'Size use 2; 18499@end example 18500 18501Although the default size of type @code{Small} is 4, the @code{Size} 18502clause is accepted by GNAT and results in the following representation 18503scheme: 18504 18505@example 18506-7 is represented as 2#00# 18507-6 is represented as 2#01# 18508-5 is represented as 2#10# 18509-4 is represented as 2#11# 18510@end example 18511 18512Biased representation is only used if the specified @code{Size} clause 18513cannot be accepted in any other manner. These reduced sizes that force 18514biased representation can be used for all discrete types except for 18515enumeration types for which a representation clause is given. 18516 18517@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18518@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{279} 18519@section Value_Size and Object_Size Clauses 18520 18521 18522@geindex Value_Size 18523 18524@geindex Object_Size 18525 18526@geindex Size 18527@geindex of objects 18528 18529In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 18530number of bits required to hold values of type @code{T}. 18531Although this interpretation was allowed in Ada 83, it was not required, 18532and this requirement in practice can cause some significant difficulties. 18533For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 18534However, in Ada 95 and Ada 2005, 18535@code{Natural'Size} is 18536typically 31. This means that code may change in behavior when moving 18537from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18538 18539@example 18540type Rec is record; 18541 A : Natural; 18542 B : Natural; 18543end record; 18544 18545for Rec use record 18546 at 0 range 0 .. Natural'Size - 1; 18547 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18548end record; 18549@end example 18550 18551In the above code, since the typical size of @code{Natural} objects 18552is 32 bits and @code{Natural'Size} is 31, the above code can cause 18553unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18554there are cases where the fact that the object size can exceed the 18555size of the type causes surprises. 18556 18557To help get around this problem GNAT provides two implementation 18558defined attributes, @code{Value_Size} and @code{Object_Size}. When 18559applied to a type, these attributes yield the size of the type 18560(corresponding to the RM defined size attribute), and the size of 18561objects of the type respectively. 18562 18563The @code{Object_Size} is used for determining the default size of 18564objects and components. This size value can be referred to using the 18565@code{Object_Size} attribute. The phrase 'is used' here means that it is 18566the basis of the determination of the size. The backend is free to 18567pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18568character might be stored in 32 bits on a machine with no efficient 18569byte access instructions such as the Alpha. 18570 18571The default rules for the value of @code{Object_Size} for 18572discrete types are as follows: 18573 18574 18575@itemize * 18576 18577@item 18578The @code{Object_Size} for base subtypes reflect the natural hardware 18579size in bits (run the compiler with @emph{-gnatS} to find those values 18580for numeric types). Enumeration types and fixed-point base subtypes have 185818, 16, 32, or 64 bits for this size, depending on the range of values 18582to be stored. 18583 18584@item 18585The @code{Object_Size} of a subtype is the same as the 18586@code{Object_Size} of 18587the type from which it is obtained. 18588 18589@item 18590The @code{Object_Size} of a derived base type is copied from the parent 18591base type, and the @code{Object_Size} of a derived first subtype is copied 18592from the parent first subtype. 18593@end itemize 18594 18595The @code{Value_Size} attribute 18596is the (minimum) number of bits required to store a value 18597of the type. 18598This value is used to determine how tightly to pack 18599records or arrays with components of this type, and also affects 18600the semantics of unchecked conversion (unchecked conversions where 18601the @code{Value_Size} values differ generate a warning, and are potentially 18602target dependent). 18603 18604The default rules for the value of @code{Value_Size} are as follows: 18605 18606 18607@itemize * 18608 18609@item 18610The @code{Value_Size} for a base subtype is the minimum number of bits 18611required to store all values of the type (including the sign bit 18612only if negative values are possible). 18613 18614@item 18615If a subtype statically matches the first subtype of a given type, then it has 18616by default the same @code{Value_Size} as the first subtype. This is a 18617consequence of RM 13.1(14): "if two subtypes statically match, 18618then their subtype-specific aspects are the same".) 18619 18620@item 18621All other subtypes have a @code{Value_Size} corresponding to the minimum 18622number of bits required to store all values of the subtype. For 18623dynamic bounds, it is assumed that the value can range down or up 18624to the corresponding bound of the ancestor 18625@end itemize 18626 18627The RM defined attribute @code{Size} corresponds to the 18628@code{Value_Size} attribute. 18629 18630The @code{Size} attribute may be defined for a first-named subtype. This sets 18631the @code{Value_Size} of 18632the first-named subtype to the given value, and the 18633@code{Object_Size} of this first-named subtype to the given value padded up 18634to an appropriate boundary. It is a consequence of the default rules 18635above that this @code{Object_Size} will apply to all further subtypes. On the 18636other hand, @code{Value_Size} is affected only for the first subtype, any 18637dynamic subtypes obtained from it directly, and any statically matching 18638subtypes. The @code{Value_Size} of any other static subtypes is not affected. 18639 18640@code{Value_Size} and 18641@code{Object_Size} may be explicitly set for any subtype using 18642an attribute definition clause. Note that the use of these attributes 18643can cause the RM 13.1(14) rule to be violated. If two access types 18644reference aliased objects whose subtypes have differing @code{Object_Size} 18645values as a result of explicit attribute definition clauses, then it 18646is illegal to convert from one access subtype to the other. For a more 18647complete description of this additional legality rule, see the 18648description of the @code{Object_Size} attribute. 18649 18650To get a feel for the difference, consider the following examples (note 18651that in each case the base is @code{Short_Short_Integer} with a size of 8): 18652 18653 18654@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 18655@headitem 18656 18657Type or subtype declaration 18658 18659@tab 18660 18661Object_Size 18662 18663@tab 18664 18665Value_Size 18666 18667@item 18668 18669@code{type x1 is range 0 .. 5;} 18670 18671@tab 18672 186738 18674 18675@tab 18676 186773 18678 18679@item 18680 18681@code{type x2 is range 0 .. 5;} 18682@code{for x2'size use 12;} 18683 18684@tab 18685 1868616 18687 18688@tab 18689 1869012 18691 18692@item 18693 18694@code{subtype x3 is x2 range 0 .. 3;} 18695 18696@tab 18697 1869816 18699 18700@tab 18701 187022 18703 18704@item 18705 18706@code{subtype x4 is x2'base range 0 .. 10;} 18707 18708@tab 18709 187108 18711 18712@tab 18713 187144 18715 18716@item 18717 18718@code{dynamic : x2'Base range -64 .. +63;} 18719 18720@tab 18721 18722@tab 18723 18724@item 18725 18726@code{subtype x5 is x2 range 0 .. dynamic;} 18727 18728@tab 18729 1873016 18731 18732@tab 18733 187343* 18735 18736@item 18737 18738@code{subtype x6 is x2'base range 0 .. dynamic;} 18739 18740@tab 18741 187428 18743 18744@tab 18745 187467* 18747 18748@end multitable 18749 18750 18751Note: the entries marked '*' are not actually specified by the Ada 18752Reference Manual, which has nothing to say about size in the dynamic 18753case. What GNAT does is to allocate sufficient bits to accomodate any 18754possible dynamic values for the bounds at run-time. 18755 18756So far, so good, but GNAT has to obey the RM rules, so the question is 18757under what conditions must the RM @code{Size} be used. 18758The following is a list 18759of the occasions on which the RM @code{Size} must be used: 18760 18761 18762@itemize * 18763 18764@item 18765Component size for packed arrays or records 18766 18767@item 18768Value of the attribute @code{Size} for a type 18769 18770@item 18771Warning about sizes not matching for unchecked conversion 18772@end itemize 18773 18774For record types, the @code{Object_Size} is always a multiple of the 18775alignment of the type (this is true for all types). In some cases the 18776@code{Value_Size} can be smaller. Consider: 18777 18778@example 18779type R is record 18780 X : Integer; 18781 Y : Character; 18782end record; 18783@end example 18784 18785On a typical 32-bit architecture, the X component will be four bytes, and 18786require four-byte alignment, and the Y component will be one byte. In this 18787case @code{R'Value_Size} will be 40 (bits) since this is the minimum size 18788required to store a value of this type, and for example, it is permissible 18789to have a component of type R in an outer array whose component size is 18790specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), 18791since it must be rounded up so that this value is a multiple of the 18792alignment (4 bytes = 32 bits). 18793 18794For all other types, the @code{Object_Size} 18795and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). 18796Only @code{Size} may be specified for such types. 18797 18798Note that @code{Value_Size} can be used to force biased representation 18799for a particular subtype. Consider this example: 18800 18801@example 18802type R is (A, B, C, D, E, F); 18803subtype RAB is R range A .. B; 18804subtype REF is R range E .. F; 18805@end example 18806 18807By default, @code{RAB} 18808has a size of 1 (sufficient to accommodate the representation 18809of @code{A} and @code{B}, 0 and 1), and @code{REF} 18810has a size of 3 (sufficient to accommodate the representation 18811of @code{E} and @code{F}, 4 and 5). But if we add the 18812following @code{Value_Size} attribute definition clause: 18813 18814@example 18815for REF'Value_Size use 1; 18816@end example 18817 18818then biased representation is forced for @code{REF}, 18819and 0 will represent @code{E} and 1 will represent @code{F}. 18820A warning is issued when a @code{Value_Size} attribute 18821definition clause forces biased representation. This 18822warning can be turned off using @code{-gnatw.B}. 18823 18824@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 18825@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{27a}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{27b} 18826@section Component_Size Clauses 18827 18828 18829@geindex Component_Size Clause 18830 18831Normally, the value specified in a component size clause must be consistent 18832with the subtype of the array component with regard to size and alignment. 18833In other words, the value specified must be at least equal to the size 18834of this subtype, and must be a multiple of the alignment value. 18835 18836In addition, component size clauses are allowed which cause the array 18837to be packed, by specifying a smaller value. A first case is for 18838component size values in the range 1 through 63. The value specified 18839must not be smaller than the Size of the subtype. GNAT will accurately 18840honor all packing requests in this range. For example, if we have: 18841 18842@example 18843type r is array (1 .. 8) of Natural; 18844for r'Component_Size use 31; 18845@end example 18846 18847then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 18848Of course access to the components of such an array is considerably 18849less efficient than if the natural component size of 32 is used. 18850A second case is when the subtype of the component is a record type 18851padded because of its default alignment. For example, if we have: 18852 18853@example 18854type r is record 18855 i : Integer; 18856 j : Integer; 18857 b : Boolean; 18858end record; 18859 18860type a is array (1 .. 8) of r; 18861for a'Component_Size use 72; 18862@end example 18863 18864then the resulting array has a length of 72 bytes, instead of 96 bytes 18865if the alignment of the record (4) was obeyed. 18866 18867Note that there is no point in giving both a component size clause 18868and a pragma Pack for the same array type. if such duplicate 18869clauses are given, the pragma Pack will be ignored. 18870 18871@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 18872@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{27c}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{27d} 18873@section Bit_Order Clauses 18874 18875 18876@geindex Bit_Order Clause 18877 18878@geindex bit ordering 18879 18880@geindex ordering 18881@geindex of bits 18882 18883For record subtypes, GNAT permits the specification of the @code{Bit_Order} 18884attribute. The specification may either correspond to the default bit 18885order for the target, in which case the specification has no effect and 18886places no additional restrictions, or it may be for the non-standard 18887setting (that is the opposite of the default). 18888 18889In the case where the non-standard value is specified, the effect is 18890to renumber bits within each byte, but the ordering of bytes is not 18891affected. There are certain 18892restrictions placed on component clauses as follows: 18893 18894 18895@itemize * 18896 18897@item 18898Components fitting within a single storage unit. 18899 18900These are unrestricted, and the effect is merely to renumber bits. For 18901example if we are on a little-endian machine with @code{Low_Order_First} 18902being the default, then the following two declarations have exactly 18903the same effect: 18904 18905@example 18906type R1 is record 18907 A : Boolean; 18908 B : Integer range 1 .. 120; 18909end record; 18910 18911for R1 use record 18912 A at 0 range 0 .. 0; 18913 B at 0 range 1 .. 7; 18914end record; 18915 18916type R2 is record 18917 A : Boolean; 18918 B : Integer range 1 .. 120; 18919end record; 18920 18921for R2'Bit_Order use High_Order_First; 18922 18923for R2 use record 18924 A at 0 range 7 .. 7; 18925 B at 0 range 0 .. 6; 18926end record; 18927@end example 18928 18929The useful application here is to write the second declaration with the 18930@code{Bit_Order} attribute definition clause, and know that it will be treated 18931the same, regardless of whether the target is little-endian or big-endian. 18932 18933@item 18934Components occupying an integral number of bytes. 18935 18936These are components that exactly fit in two or more bytes. Such component 18937declarations are allowed, but have no effect, since it is important to realize 18938that the @code{Bit_Order} specification does not affect the ordering of bytes. 18939In particular, the following attempt at getting an endian-independent integer 18940does not work: 18941 18942@example 18943type R2 is record 18944 A : Integer; 18945end record; 18946 18947for R2'Bit_Order use High_Order_First; 18948 18949for R2 use record 18950 A at 0 range 0 .. 31; 18951end record; 18952@end example 18953 18954This declaration will result in a little-endian integer on a 18955little-endian machine, and a big-endian integer on a big-endian machine. 18956If byte flipping is required for interoperability between big- and 18957little-endian machines, this must be explicitly programmed. This capability 18958is not provided by @code{Bit_Order}. 18959 18960@item 18961Components that are positioned across byte boundaries. 18962 18963but do not occupy an integral number of bytes. Given that bytes are not 18964reordered, such fields would occupy a non-contiguous sequence of bits 18965in memory, requiring non-trivial code to reassemble. They are for this 18966reason not permitted, and any component clause specifying such a layout 18967will be flagged as illegal by GNAT. 18968@end itemize 18969 18970Since the misconception that Bit_Order automatically deals with all 18971endian-related incompatibilities is a common one, the specification of 18972a component field that is an integral number of bytes will always 18973generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} 18974if desired. The following section contains additional 18975details regarding the issue of byte ordering. 18976 18977@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 18978@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{27e}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{27f} 18979@section Effect of Bit_Order on Byte Ordering 18980 18981 18982@geindex byte ordering 18983 18984@geindex ordering 18985@geindex of bytes 18986 18987In this section we will review the effect of the @code{Bit_Order} attribute 18988definition clause on byte ordering. Briefly, it has no effect at all, but 18989a detailed example will be helpful. Before giving this 18990example, let us review the precise 18991definition of the effect of defining @code{Bit_Order}. The effect of a 18992non-standard bit order is described in section 13.5.3 of the Ada 18993Reference Manual: 18994 18995@quotation 18996 18997"2 A bit ordering is a method of interpreting the meaning of 18998the storage place attributes." 18999@end quotation 19000 19001To understand the precise definition of storage place attributes in 19002this context, we visit section 13.5.1 of the manual: 19003 19004@quotation 19005 19006"13 A record_representation_clause (without the mod_clause) 19007specifies the layout. The storage place attributes (see 13.5.2) 19008are taken from the values of the position, first_bit, and last_bit 19009expressions after normalizing those values so that first_bit is 19010less than Storage_Unit." 19011@end quotation 19012 19013The critical point here is that storage places are taken from 19014the values after normalization, not before. So the @code{Bit_Order} 19015interpretation applies to normalized values. The interpretation 19016is described in the later part of the 13.5.3 paragraph: 19017 19018@quotation 19019 19020"2 A bit ordering is a method of interpreting the meaning of 19021the storage place attributes. High_Order_First (known in the 19022vernacular as 'big endian') means that the first bit of a 19023storage element (bit 0) is the most significant bit (interpreting 19024the sequence of bits that represent a component as an unsigned 19025integer value). Low_Order_First (known in the vernacular as 19026'little endian') means the opposite: the first bit is the 19027least significant." 19028@end quotation 19029 19030Note that the numbering is with respect to the bits of a storage 19031unit. In other words, the specification affects only the numbering 19032of bits within a single storage unit. 19033 19034We can make the effect clearer by giving an example. 19035 19036Suppose that we have an external device which presents two bytes, the first 19037byte presented, which is the first (low addressed byte) of the two byte 19038record is called Master, and the second byte is called Slave. 19039 19040The left most (most significant bit is called Control for each byte, and 19041the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost 19042(least significant) bit. 19043 19044On a big-endian machine, we can write the following representation clause 19045 19046@example 19047type Data is record 19048 Master_Control : Bit; 19049 Master_V1 : Bit; 19050 Master_V2 : Bit; 19051 Master_V3 : Bit; 19052 Master_V4 : Bit; 19053 Master_V5 : Bit; 19054 Master_V6 : Bit; 19055 Master_V7 : Bit; 19056 Slave_Control : Bit; 19057 Slave_V1 : Bit; 19058 Slave_V2 : Bit; 19059 Slave_V3 : Bit; 19060 Slave_V4 : Bit; 19061 Slave_V5 : Bit; 19062 Slave_V6 : Bit; 19063 Slave_V7 : Bit; 19064end record; 19065 19066for Data use record 19067 Master_Control at 0 range 0 .. 0; 19068 Master_V1 at 0 range 1 .. 1; 19069 Master_V2 at 0 range 2 .. 2; 19070 Master_V3 at 0 range 3 .. 3; 19071 Master_V4 at 0 range 4 .. 4; 19072 Master_V5 at 0 range 5 .. 5; 19073 Master_V6 at 0 range 6 .. 6; 19074 Master_V7 at 0 range 7 .. 7; 19075 Slave_Control at 1 range 0 .. 0; 19076 Slave_V1 at 1 range 1 .. 1; 19077 Slave_V2 at 1 range 2 .. 2; 19078 Slave_V3 at 1 range 3 .. 3; 19079 Slave_V4 at 1 range 4 .. 4; 19080 Slave_V5 at 1 range 5 .. 5; 19081 Slave_V6 at 1 range 6 .. 6; 19082 Slave_V7 at 1 range 7 .. 7; 19083end record; 19084@end example 19085 19086Now if we move this to a little endian machine, then the bit ordering within 19087the byte is backwards, so we have to rewrite the record rep clause as: 19088 19089@example 19090for Data use record 19091 Master_Control at 0 range 7 .. 7; 19092 Master_V1 at 0 range 6 .. 6; 19093 Master_V2 at 0 range 5 .. 5; 19094 Master_V3 at 0 range 4 .. 4; 19095 Master_V4 at 0 range 3 .. 3; 19096 Master_V5 at 0 range 2 .. 2; 19097 Master_V6 at 0 range 1 .. 1; 19098 Master_V7 at 0 range 0 .. 0; 19099 Slave_Control at 1 range 7 .. 7; 19100 Slave_V1 at 1 range 6 .. 6; 19101 Slave_V2 at 1 range 5 .. 5; 19102 Slave_V3 at 1 range 4 .. 4; 19103 Slave_V4 at 1 range 3 .. 3; 19104 Slave_V5 at 1 range 2 .. 2; 19105 Slave_V6 at 1 range 1 .. 1; 19106 Slave_V7 at 1 range 0 .. 0; 19107end record; 19108@end example 19109 19110It is a nuisance to have to rewrite the clause, especially if 19111the code has to be maintained on both machines. However, 19112this is a case that we can handle with the 19113@code{Bit_Order} attribute if it is implemented. 19114Note that the implementation is not required on byte addressed 19115machines, but it is indeed implemented in GNAT. 19116This means that we can simply use the 19117first record clause, together with the declaration 19118 19119@example 19120for Data'Bit_Order use High_Order_First; 19121@end example 19122 19123and the effect is what is desired, namely the layout is exactly the same, 19124independent of whether the code is compiled on a big-endian or little-endian 19125machine. 19126 19127The important point to understand is that byte ordering is not affected. 19128A @code{Bit_Order} attribute definition never affects which byte a field 19129ends up in, only where it ends up in that byte. 19130To make this clear, let us rewrite the record rep clause of the previous 19131example as: 19132 19133@example 19134for Data'Bit_Order use High_Order_First; 19135for Data use record 19136 Master_Control at 0 range 0 .. 0; 19137 Master_V1 at 0 range 1 .. 1; 19138 Master_V2 at 0 range 2 .. 2; 19139 Master_V3 at 0 range 3 .. 3; 19140 Master_V4 at 0 range 4 .. 4; 19141 Master_V5 at 0 range 5 .. 5; 19142 Master_V6 at 0 range 6 .. 6; 19143 Master_V7 at 0 range 7 .. 7; 19144 Slave_Control at 0 range 8 .. 8; 19145 Slave_V1 at 0 range 9 .. 9; 19146 Slave_V2 at 0 range 10 .. 10; 19147 Slave_V3 at 0 range 11 .. 11; 19148 Slave_V4 at 0 range 12 .. 12; 19149 Slave_V5 at 0 range 13 .. 13; 19150 Slave_V6 at 0 range 14 .. 14; 19151 Slave_V7 at 0 range 15 .. 15; 19152end record; 19153@end example 19154 19155This is exactly equivalent to saying (a repeat of the first example): 19156 19157@example 19158for Data'Bit_Order use High_Order_First; 19159for Data use record 19160 Master_Control at 0 range 0 .. 0; 19161 Master_V1 at 0 range 1 .. 1; 19162 Master_V2 at 0 range 2 .. 2; 19163 Master_V3 at 0 range 3 .. 3; 19164 Master_V4 at 0 range 4 .. 4; 19165 Master_V5 at 0 range 5 .. 5; 19166 Master_V6 at 0 range 6 .. 6; 19167 Master_V7 at 0 range 7 .. 7; 19168 Slave_Control at 1 range 0 .. 0; 19169 Slave_V1 at 1 range 1 .. 1; 19170 Slave_V2 at 1 range 2 .. 2; 19171 Slave_V3 at 1 range 3 .. 3; 19172 Slave_V4 at 1 range 4 .. 4; 19173 Slave_V5 at 1 range 5 .. 5; 19174 Slave_V6 at 1 range 6 .. 6; 19175 Slave_V7 at 1 range 7 .. 7; 19176end record; 19177@end example 19178 19179Why are they equivalent? Well take a specific field, the @code{Slave_V2} 19180field. The storage place attributes are obtained by normalizing the 19181values given so that the @code{First_Bit} value is less than 8. After 19182normalizing the values (0,10,10) we get (1,2,2) which is exactly what 19183we specified in the other case. 19184 19185Now one might expect that the @code{Bit_Order} attribute might affect 19186bit numbering within the entire record component (two bytes in this 19187case, thus affecting which byte fields end up in), but that is not 19188the way this feature is defined, it only affects numbering of bits, 19189not which byte they end up in. 19190 19191Consequently it never makes sense to specify a starting bit number 19192greater than 7 (for a byte addressable field) if an attribute 19193definition for @code{Bit_Order} has been given, and indeed it 19194may be actively confusing to specify such a value, so the compiler 19195generates a warning for such usage. 19196 19197If you do need to control byte ordering then appropriate conditional 19198values must be used. If in our example, the slave byte came first on 19199some machines we might write: 19200 19201@example 19202Master_Byte_First constant Boolean := ...; 19203 19204Master_Byte : constant Natural := 19205 1 - Boolean'Pos (Master_Byte_First); 19206Slave_Byte : constant Natural := 19207 Boolean'Pos (Master_Byte_First); 19208 19209for Data'Bit_Order use High_Order_First; 19210for Data use record 19211 Master_Control at Master_Byte range 0 .. 0; 19212 Master_V1 at Master_Byte range 1 .. 1; 19213 Master_V2 at Master_Byte range 2 .. 2; 19214 Master_V3 at Master_Byte range 3 .. 3; 19215 Master_V4 at Master_Byte range 4 .. 4; 19216 Master_V5 at Master_Byte range 5 .. 5; 19217 Master_V6 at Master_Byte range 6 .. 6; 19218 Master_V7 at Master_Byte range 7 .. 7; 19219 Slave_Control at Slave_Byte range 0 .. 0; 19220 Slave_V1 at Slave_Byte range 1 .. 1; 19221 Slave_V2 at Slave_Byte range 2 .. 2; 19222 Slave_V3 at Slave_Byte range 3 .. 3; 19223 Slave_V4 at Slave_Byte range 4 .. 4; 19224 Slave_V5 at Slave_Byte range 5 .. 5; 19225 Slave_V6 at Slave_Byte range 6 .. 6; 19226 Slave_V7 at Slave_Byte range 7 .. 7; 19227end record; 19228@end example 19229 19230Now to switch between machines, all that is necessary is 19231to set the boolean constant @code{Master_Byte_First} in 19232an appropriate manner. 19233 19234@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 19235@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{280}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{281} 19236@section Pragma Pack for Arrays 19237 19238 19239@geindex Pragma Pack (for arrays) 19240 19241Pragma @code{Pack} applied to an array has an effect that depends upon whether the 19242component type is @emph{packable}. For a component type to be @emph{packable}, it must 19243be one of the following cases: 19244 19245 19246@itemize * 19247 19248@item 19249Any elementary type. 19250 19251@item 19252Any small packed array type with a static size. 19253 19254@item 19255Any small simple record type with a static size. 19256@end itemize 19257 19258For all these cases, if the component subtype size is in the range 192591 through 64, then the effect of the pragma @code{Pack} is exactly as though a 19260component size were specified giving the component subtype size. 19261 19262All other types are non-packable, they occupy an integral number of storage 19263units and the only effect of pragma Pack is to remove alignment gaps. 19264 19265For example if we have: 19266 19267@example 19268type r is range 0 .. 17; 19269 19270type ar is array (1 .. 8) of r; 19271pragma Pack (ar); 19272@end example 19273 19274Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, 19275and the size of the array @code{ar} will be exactly 40 bits). 19276 19277Note that in some cases this rather fierce approach to packing can produce 19278unexpected effects. For example, in Ada 95 and Ada 2005, 19279subtype @code{Natural} typically has a size of 31, meaning that if you 19280pack an array of @code{Natural}, you get 31-bit 19281close packing, which saves a few bits, but results in far less efficient 19282access. Since many other Ada compilers will ignore such a packing request, 19283GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 19284might not be what is intended. You can easily remove this warning by 19285using an explicit @code{Component_Size} setting instead, which never generates 19286a warning, since the intention of the programmer is clear in this case. 19287 19288GNAT treats packed arrays in one of two ways. If the size of the array is 19289known at compile time and is less than 64 bits, then internally the array 19290is represented as a single modular type, of exactly the appropriate number 19291of bits. If the length is greater than 63 bits, or is not known at compile 19292time, then the packed array is represented as an array of bytes, and the 19293length is always a multiple of 8 bits. 19294 19295Note that to represent a packed array as a modular type, the alignment must 19296be suitable for the modular type involved. For example, on typical machines 19297a 32-bit packed array will be represented by a 32-bit modular integer with 19298an alignment of four bytes. If you explicitly override the default alignment 19299with an alignment clause that is too small, the modular representation 19300cannot be used. For example, consider the following set of declarations: 19301 19302@example 19303type R is range 1 .. 3; 19304type S is array (1 .. 31) of R; 19305for S'Component_Size use 2; 19306for S'Size use 62; 19307for S'Alignment use 1; 19308@end example 19309 19310If the alignment clause were not present, then a 62-bit modular 19311representation would be chosen (typically with an alignment of 4 or 8 19312bytes depending on the target). But the default alignment is overridden 19313with the explicit alignment clause. This means that the modular 19314representation cannot be used, and instead the array of bytes 19315representation must be used, meaning that the length must be a multiple 19316of 8. Thus the above set of declarations will result in a diagnostic 19317rejecting the size clause and noting that the minimum size allowed is 64. 19318 19319@geindex Pragma Pack (for type Natural) 19320 19321@geindex Pragma Pack warning 19322 19323One special case that is worth noting occurs when the base type of the 19324component size is 8/16/32 and the subtype is one bit less. Notably this 19325occurs with subtype @code{Natural}. Consider: 19326 19327@example 19328type Arr is array (1 .. 32) of Natural; 19329pragma Pack (Arr); 19330@end example 19331 19332In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 19333since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 19334Ada 83 compilers did not attempt 31 bit packing. 19335 19336In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 19337GNAT really does pack 31-bit subtype to 31 bits. This may result in a 19338substantial unintended performance penalty when porting legacy Ada 83 code. 19339To help prevent this, GNAT generates a warning in such cases. If you really 19340want 31 bit packing in a case like this, you can set the component size 19341explicitly: 19342 19343@example 19344type Arr is array (1 .. 32) of Natural; 19345for Arr'Component_Size use 31; 19346@end example 19347 19348Here 31-bit packing is achieved as required, and no warning is generated, 19349since in this case the programmer intention is clear. 19350 19351@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 19352@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{282}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{283} 19353@section Pragma Pack for Records 19354 19355 19356@geindex Pragma Pack (for records) 19357 19358Pragma @code{Pack} applied to a record will pack the components to reduce 19359wasted space from alignment gaps and by reducing the amount of space 19360taken by components. We distinguish between @emph{packable} components and 19361@emph{non-packable} components. 19362Components of the following types are considered packable: 19363 19364 19365@itemize * 19366 19367@item 19368Components of an elementary type are packable unless they are aliased, 19369independent, or of an atomic type. 19370 19371@item 19372Small packed arrays, where the size is statically known, are represented 19373internally as modular integers, and so they are also packable. 19374 19375@item 19376Small simple records, where the size is statically known, are also packable. 19377@end itemize 19378 19379For all these cases, if the @code{'Size} value is in the range 1 through 64, the 19380components occupy the exact number of bits corresponding to this value 19381and are packed with no padding bits, i.e. they can start on an arbitrary 19382bit boundary. 19383 19384All other types are non-packable, they occupy an integral number of storage 19385units and the only effect of pragma @code{Pack} is to remove alignment gaps. 19386 19387For example, consider the record 19388 19389@example 19390type Rb1 is array (1 .. 13) of Boolean; 19391pragma Pack (Rb1); 19392 19393type Rb2 is array (1 .. 65) of Boolean; 19394pragma Pack (Rb2); 19395 19396type AF is new Float with Atomic; 19397 19398type X2 is record 19399 L1 : Boolean; 19400 L2 : Duration; 19401 L3 : AF; 19402 L4 : Boolean; 19403 L5 : Rb1; 19404 L6 : Rb2; 19405end record; 19406pragma Pack (X2); 19407@end example 19408 19409The representation for the record @code{X2} is as follows: 19410 19411@example 19412for X2'Size use 224; 19413for X2 use record 19414 L1 at 0 range 0 .. 0; 19415 L2 at 0 range 1 .. 64; 19416 L3 at 12 range 0 .. 31; 19417 L4 at 16 range 0 .. 0; 19418 L5 at 16 range 1 .. 13; 19419 L6 at 18 range 0 .. 71; 19420end record; 19421@end example 19422 19423Studying this example, we see that the packable fields @code{L1} 19424and @code{L2} are 19425of length equal to their sizes, and placed at specific bit boundaries (and 19426not byte boundaries) to 19427eliminate padding. But @code{L3} is of a non-packable float type (because 19428it is aliased), so it is on the next appropriate alignment boundary. 19429 19430The next two fields are fully packable, so @code{L4} and @code{L5} are 19431minimally packed with no gaps. However, type @code{Rb2} is a packed 19432array that is longer than 64 bits, so it is itself non-packable. Thus 19433the @code{L6} field is aligned to the next byte boundary, and takes an 19434integral number of bytes, i.e., 72 bits. 19435 19436@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19437@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{285} 19438@section Record Representation Clauses 19439 19440 19441@geindex Record Representation Clause 19442 19443Record representation clauses may be given for all record types, including 19444types obtained by record extension. Component clauses are allowed for any 19445static component. The restrictions on component clauses depend on the type 19446of the component. 19447 19448@geindex Component Clause 19449 19450For all components of an elementary type, the only restriction on component 19451clauses is that the size must be at least the @code{'Size} value of the type 19452(actually the Value_Size). There are no restrictions due to alignment, 19453and such components may freely cross storage boundaries. 19454 19455Packed arrays with a size up to and including 64 bits are represented 19456internally using a modular type with the appropriate number of bits, and 19457thus the same lack of restriction applies. For example, if you declare: 19458 19459@example 19460type R is array (1 .. 49) of Boolean; 19461pragma Pack (R); 19462for R'Size use 49; 19463@end example 19464 19465then a component clause for a component of type @code{R} may start on any 19466specified bit boundary, and may specify a value of 49 bits or greater. 19467 19468For packed bit arrays that are longer than 64 bits, there are two 19469cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 19470including the important case of single bits or boolean values, then 19471there are no limitations on placement of such components, and they 19472may start and end at arbitrary bit boundaries. 19473 19474If the component size is not a power of 2 (e.g., 3 or 5), then 19475an array of this type longer than 64 bits must always be placed on 19476on a storage unit (byte) boundary and occupy an integral number 19477of storage units (bytes). Any component clause that does not 19478meet this requirement will be rejected. 19479 19480Any aliased component, or component of an aliased type, must 19481have its normal alignment and size. A component clause that 19482does not meet this requirement will be rejected. 19483 19484The tag field of a tagged type always occupies an address sized field at 19485the start of the record. No component clause may attempt to overlay this 19486tag. When a tagged type appears as a component, the tag field must have 19487proper alignment 19488 19489In the case of a record extension @code{T1}, of a type @code{T}, no component clause applied 19490to the type @code{T1} can specify a storage location that would overlap the first 19491@code{T'Size} bytes of the record. 19492 19493For all other component types, including non-bit-packed arrays, 19494the component can be placed at an arbitrary bit boundary, 19495so for example, the following is permitted: 19496 19497@example 19498type R is array (1 .. 10) of Boolean; 19499for R'Size use 80; 19500 19501type Q is record 19502 G, H : Boolean; 19503 L, M : R; 19504end record; 19505 19506for Q use record 19507 G at 0 range 0 .. 0; 19508 H at 0 range 1 .. 1; 19509 L at 0 range 2 .. 81; 19510 R at 0 range 82 .. 161; 19511end record; 19512@end example 19513 19514@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19515@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{286}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{287} 19516@section Handling of Records with Holes 19517 19518 19519@geindex Handling of Records with Holes 19520 19521As a result of alignment considerations, records may contain "holes" 19522or gaps 19523which do not correspond to the data bits of any of the components. 19524Record representation clauses can also result in holes in records. 19525 19526GNAT does not attempt to clear these holes, so in record objects, 19527they should be considered to hold undefined rubbish. The generated 19528equality routine just tests components so does not access these 19529undefined bits, and assignment and copy operations may or may not 19530preserve the contents of these holes (for assignments, the holes 19531in the target will in practice contain either the bits that are 19532present in the holes in the source, or the bits that were present 19533in the target before the assignment). 19534 19535If it is necessary to ensure that holes in records have all zero 19536bits, then record objects for which this initialization is desired 19537should be explicitly set to all zero values using Unchecked_Conversion 19538or address overlays. For example 19539 19540@example 19541type HRec is record 19542 C : Character; 19543 I : Integer; 19544end record; 19545@end example 19546 19547On typical machines, integers need to be aligned on a four-byte 19548boundary, resulting in three bytes of undefined rubbish following 19549the 8-bit field for C. To ensure that the hole in a variable of 19550type HRec is set to all zero bits, 19551you could for example do: 19552 19553@example 19554type Base is record 19555 Dummy1, Dummy2 : Integer := 0; 19556end record; 19557 19558BaseVar : Base; 19559RealVar : Hrec; 19560for RealVar'Address use BaseVar'Address; 19561@end example 19562 19563Now the 8-bytes of the value of RealVar start out containing all zero 19564bits. A safer approach is to just define dummy fields, avoiding the 19565holes, as in: 19566 19567@example 19568type HRec is record 19569 C : Character; 19570 Dummy1 : Short_Short_Integer := 0; 19571 Dummy2 : Short_Short_Integer := 0; 19572 Dummy3 : Short_Short_Integer := 0; 19573 I : Integer; 19574end record; 19575@end example 19576 19577And to make absolutely sure that the intent of this is followed, you 19578can use representation clauses: 19579 19580@example 19581for Hrec use record 19582 C at 0 range 0 .. 7; 19583 Dummy1 at 1 range 0 .. 7; 19584 Dummy2 at 2 range 0 .. 7; 19585 Dummy3 at 3 range 0 .. 7; 19586 I at 4 range 0 .. 31; 19587end record; 19588for Hrec'Size use 64; 19589@end example 19590 19591@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 19592@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{288}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{289} 19593@section Enumeration Clauses 19594 19595 19596The only restriction on enumeration clauses is that the range of values 19597must be representable. For the signed case, if one or more of the 19598representation values are negative, all values must be in the range: 19599 19600@example 19601System.Min_Int .. System.Max_Int 19602@end example 19603 19604For the unsigned case, where all values are nonnegative, the values must 19605be in the range: 19606 19607@example 196080 .. System.Max_Binary_Modulus; 19609@end example 19610 19611A @emph{confirming} representation clause is one in which the values range 19612from 0 in sequence, i.e., a clause that confirms the default representation 19613for an enumeration type. 19614Such a confirming representation 19615is permitted by these rules, and is specially recognized by the compiler so 19616that no extra overhead results from the use of such a clause. 19617 19618If an array has an index type which is an enumeration type to which an 19619enumeration clause has been applied, then the array is stored in a compact 19620manner. Consider the declarations: 19621 19622@example 19623type r is (A, B, C); 19624for r use (A => 1, B => 5, C => 10); 19625type t is array (r) of Character; 19626@end example 19627 19628The array type t corresponds to a vector with exactly three elements and 19629has a default size equal to @code{3*Character'Size}. This ensures efficient 19630use of space, but means that accesses to elements of the array will incur 19631the overhead of converting representation values to the corresponding 19632positional values, (i.e., the value delivered by the @code{Pos} attribute). 19633 19634@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 19635@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{28a}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{28b} 19636@section Address Clauses 19637 19638 19639@geindex Address Clause 19640 19641The reference manual allows a general restriction on representation clauses, 19642as found in RM 13.1(22): 19643 19644@quotation 19645 19646"An implementation need not support representation 19647items containing nonstatic expressions, except that 19648an implementation should support a representation item 19649for a given entity if each nonstatic expression in the 19650representation item is a name that statically denotes 19651a constant declared before the entity." 19652@end quotation 19653 19654In practice this is applicable only to address clauses, since this is the 19655only case in which a nonstatic expression is permitted by the syntax. As 19656the AARM notes in sections 13.1 (22.a-22.h): 19657 19658@quotation 19659 1966022.a Reason: This is to avoid the following sort of thing: 19661 1966222.b X : Integer := F(...); 19663Y : Address := G(...); 19664for X'Address use Y; 19665 1966622.c In the above, we have to evaluate the 19667initialization expression for X before we 19668know where to put the result. This seems 19669like an unreasonable implementation burden. 19670 1967122.d The above code should instead be written 19672like this: 19673 1967422.e Y : constant Address := G(...); 19675X : Integer := F(...); 19676for X'Address use Y; 19677 1967822.f This allows the expression 'Y' to be safely 19679evaluated before X is created. 19680 1968122.g The constant could be a formal parameter of mode in. 19682 1968322.h An implementation can support other nonstatic 19684expressions if it wants to. Expressions of type 19685Address are hardly ever static, but their value 19686might be known at compile time anyway in many 19687cases. 19688@end quotation 19689 19690GNAT does indeed permit many additional cases of nonstatic expressions. In 19691particular, if the type involved is elementary there are no restrictions 19692(since in this case, holding a temporary copy of the initialization value, 19693if one is present, is inexpensive). In addition, if there is no implicit or 19694explicit initialization, then there are no restrictions. GNAT will reject 19695only the case where all three of these conditions hold: 19696 19697 19698@itemize * 19699 19700@item 19701The type of the item is non-elementary (e.g., a record or array). 19702 19703@item 19704There is explicit or implicit initialization required for the object. 19705Note that access values are always implicitly initialized. 19706 19707@item 19708The address value is nonstatic. Here GNAT is more permissive than the 19709RM, and allows the address value to be the address of a previously declared 19710stand-alone variable, as long as it does not itself have an address clause. 19711 19712@example 19713Anchor : Some_Initialized_Type; 19714Overlay : Some_Initialized_Type; 19715for Overlay'Address use Anchor'Address; 19716@end example 19717 19718However, the prefix of the address clause cannot be an array component, or 19719a component of a discriminated record. 19720@end itemize 19721 19722As noted above in section 22.h, address values are typically nonstatic. In 19723particular the To_Address function, even if applied to a literal value, is 19724a nonstatic function call. To avoid this minor annoyance, GNAT provides 19725the implementation defined attribute 'To_Address. The following two 19726expressions have identical values: 19727 19728@geindex Attribute 19729 19730@geindex To_Address 19731 19732@example 19733To_Address (16#1234_0000#) 19734System'To_Address (16#1234_0000#); 19735@end example 19736 19737except that the second form is considered to be a static expression, and 19738thus when used as an address clause value is always permitted. 19739 19740Additionally, GNAT treats as static an address clause that is an 19741unchecked_conversion of a static integer value. This simplifies the porting 19742of legacy code, and provides a portable equivalent to the GNAT attribute 19743@code{To_Address}. 19744 19745Another issue with address clauses is the interaction with alignment 19746requirements. When an address clause is given for an object, the address 19747value must be consistent with the alignment of the object (which is usually 19748the same as the alignment of the type of the object). If an address clause 19749is given that specifies an inappropriately aligned address value, then the 19750program execution is erroneous. 19751 19752Since this source of erroneous behavior can have unfortunate effects on 19753machines with strict alignment requirements, GNAT 19754checks (at compile time if possible, generating a warning, or at execution 19755time with a run-time check) that the alignment is appropriate. If the 19756run-time check fails, then @code{Program_Error} is raised. This run-time 19757check is suppressed if range checks are suppressed, or if the special GNAT 19758check Alignment_Check is suppressed, or if 19759@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 19760suppressed by default on non-strict alignment machines (such as the x86). 19761 19762Finally, GNAT does not permit overlaying of objects of class-wide types. In 19763most cases, the compiler can detect an attempt at such overlays and will 19764generate a warning at compile time and a Program_Error exception at run time. 19765 19766@geindex Export 19767 19768An address clause cannot be given for an exported object. More 19769understandably the real restriction is that objects with an address 19770clause cannot be exported. This is because such variables are not 19771defined by the Ada program, so there is no external object to export. 19772 19773@geindex Import 19774 19775It is permissible to give an address clause and a pragma Import for the 19776same object. In this case, the variable is not really defined by the 19777Ada program, so there is no external symbol to be linked. The link name 19778and the external name are ignored in this case. The reason that we allow this 19779combination is that it provides a useful idiom to avoid unwanted 19780initializations on objects with address clauses. 19781 19782When an address clause is given for an object that has implicit or 19783explicit initialization, then by default initialization takes place. This 19784means that the effect of the object declaration is to overwrite the 19785memory at the specified address. This is almost always not what the 19786programmer wants, so GNAT will output a warning: 19787 19788@example 19789with System; 19790package G is 19791 type R is record 19792 M : Integer := 0; 19793 end record; 19794 19795 Ext : R; 19796 for Ext'Address use System'To_Address (16#1234_1234#); 19797 | 19798>>> warning: implicit initialization of "Ext" may 19799 modify overlaid storage 19800>>> warning: use pragma Import for "Ext" to suppress 19801 initialization (RM B(24)) 19802 19803end G; 19804@end example 19805 19806As indicated by the warning message, the solution is to use a (dummy) pragma 19807Import to suppress this initialization. The pragma tell the compiler that the 19808object is declared and initialized elsewhere. The following package compiles 19809without warnings (and the initialization is suppressed): 19810 19811@example 19812with System; 19813package G is 19814 type R is record 19815 M : Integer := 0; 19816 end record; 19817 19818 Ext : R; 19819 for Ext'Address use System'To_Address (16#1234_1234#); 19820 pragma Import (Ada, Ext); 19821end G; 19822@end example 19823 19824A final issue with address clauses involves their use for overlaying 19825variables, as in the following example: 19826 19827@geindex Overlaying of objects 19828 19829@example 19830A : Integer; 19831B : Integer; 19832for B'Address use A'Address; 19833@end example 19834 19835or alternatively, using the form recommended by the RM: 19836 19837@example 19838A : Integer; 19839Addr : constant Address := A'Address; 19840B : Integer; 19841for B'Address use Addr; 19842@end example 19843 19844In both of these cases, @code{A} and @code{B} become aliased to one another 19845via the address clause. This use of address clauses to overlay 19846variables, achieving an effect similar to unchecked conversion 19847was erroneous in Ada 83, but in Ada 95 and Ada 2005 19848the effect is implementation defined. Furthermore, the 19849Ada RM specifically recommends that in a situation 19850like this, @code{B} should be subject to the following 19851implementation advice (RM 13.3(19)): 19852 19853@quotation 19854 19855"19 If the Address of an object is specified, or it is imported 19856or exported, then the implementation should not perform 19857optimizations based on assumptions of no aliases." 19858@end quotation 19859 19860GNAT follows this recommendation, and goes further by also applying 19861this recommendation to the overlaid variable (@code{A} in the above example) 19862in this case. This means that the overlay works "as expected", in that 19863a modification to one of the variables will affect the value of the other. 19864 19865More generally, GNAT interprets this recommendation conservatively for 19866address clauses: in the cases other than overlays, it considers that the 19867object is effectively subject to pragma @code{Volatile} and implements the 19868associated semantics. 19869 19870Note that when address clause overlays are used in this way, there is an 19871issue of unintentional initialization, as shown by this example: 19872 19873@example 19874package Overwrite_Record is 19875 type R is record 19876 A : Character := 'C'; 19877 B : Character := 'A'; 19878 end record; 19879 X : Short_Integer := 3; 19880 Y : R; 19881 for Y'Address use X'Address; 19882 | 19883>>> warning: default initialization of "Y" may 19884 modify "X", use pragma Import for "Y" to 19885 suppress initialization (RM B.1(24)) 19886 19887end Overwrite_Record; 19888@end example 19889 19890Here the default initialization of @code{Y} will clobber the value 19891of @code{X}, which justifies the warning. The warning notes that 19892this effect can be eliminated by adding a @code{pragma Import} 19893which suppresses the initialization: 19894 19895@example 19896package Overwrite_Record is 19897 type R is record 19898 A : Character := 'C'; 19899 B : Character := 'A'; 19900 end record; 19901 X : Short_Integer := 3; 19902 Y : R; 19903 for Y'Address use X'Address; 19904 pragma Import (Ada, Y); 19905end Overwrite_Record; 19906@end example 19907 19908Note that the use of @code{pragma Initialize_Scalars} may cause variables to 19909be initialized when they would not otherwise have been in the absence 19910of the use of this pragma. This may cause an overlay to have this 19911unintended clobbering effect. The compiler avoids this for scalar 19912types, but not for composite objects (where in general the effect 19913of @code{Initialize_Scalars} is part of the initialization routine 19914for the composite object: 19915 19916@example 19917pragma Initialize_Scalars; 19918with Ada.Text_IO; use Ada.Text_IO; 19919procedure Overwrite_Array is 19920 type Arr is array (1 .. 5) of Integer; 19921 X : Arr := (others => 1); 19922 A : Arr; 19923 for A'Address use X'Address; 19924 | 19925>>> warning: default initialization of "A" may 19926 modify "X", use pragma Import for "A" to 19927 suppress initialization (RM B.1(24)) 19928 19929begin 19930 if X /= Arr'(others => 1) then 19931 Put_Line ("X was clobbered"); 19932 else 19933 Put_Line ("X was not clobbered"); 19934 end if; 19935end Overwrite_Array; 19936@end example 19937 19938The above program generates the warning as shown, and at execution 19939time, prints @code{X was clobbered}. If the @code{pragma Import} is 19940added as suggested: 19941 19942@example 19943pragma Initialize_Scalars; 19944with Ada.Text_IO; use Ada.Text_IO; 19945procedure Overwrite_Array is 19946 type Arr is array (1 .. 5) of Integer; 19947 X : Arr := (others => 1); 19948 A : Arr; 19949 for A'Address use X'Address; 19950 pragma Import (Ada, A); 19951begin 19952 if X /= Arr'(others => 1) then 19953 Put_Line ("X was clobbered"); 19954 else 19955 Put_Line ("X was not clobbered"); 19956 end if; 19957end Overwrite_Array; 19958@end example 19959 19960then the program compiles without the warning and when run will generate 19961the output @code{X was not clobbered}. 19962 19963@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 19964@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{28c}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{28d} 19965@section Use of Address Clauses for Memory-Mapped I/O 19966 19967 19968@geindex Memory-mapped I/O 19969 19970A common pattern is to use an address clause to map an atomic variable to 19971a location in memory that corresponds to a memory-mapped I/O operation or 19972operations, for example: 19973 19974@example 19975type Mem_Word is record 19976 A,B,C,D : Byte; 19977end record; 19978pragma Atomic (Mem_Word); 19979for Mem_Word_Size use 32; 19980 19981Mem : Mem_Word; 19982for Mem'Address use some-address; 19983... 19984Temp := Mem; 19985Temp.A := 32; 19986Mem := Temp; 19987@end example 19988 19989For a full access (reference or modification) of the variable (Mem) in this 19990case, as in the above examples, GNAT guarantees that the entire atomic word 19991will be accessed, in accordance with the RM C.6(15) clause. 19992 19993A problem arises with a component access such as: 19994 19995@example 19996Mem.A := 32; 19997@end example 19998 19999Note that the component A is not declared as atomic. This means that it is 20000not clear what this assignment means. It could correspond to full word read 20001and write as given in the first example, or on architectures that supported 20002such an operation it might be a single byte store instruction. The RM does 20003not have anything to say in this situation, and GNAT does not make any 20004guarantee. The code generated may vary from target to target. GNAT will issue 20005a warning in such a case: 20006 20007@example 20008Mem.A := 32; 20009| 20010>>> warning: access to non-atomic component of atomic array, 20011 may cause unexpected accesses to atomic object 20012@end example 20013 20014It is best to be explicit in this situation, by either declaring the 20015components to be atomic if you want the byte store, or explicitly writing 20016the full word access sequence if that is what the hardware requires. 20017Alternatively, if the full word access sequence is required, GNAT also 20018provides the pragma @code{Volatile_Full_Access} which can be used in lieu of 20019pragma @code{Atomic} and will give the additional guarantee. 20020 20021@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 20022@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{28e}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{28f} 20023@section Effect of Convention on Representation 20024 20025 20026@geindex Convention 20027@geindex effect on representation 20028 20029Normally the specification of a foreign language convention for a type or 20030an object has no effect on the chosen representation. In particular, the 20031representation chosen for data in GNAT generally meets the standard system 20032conventions, and for example records are laid out in a manner that is 20033consistent with C. This means that specifying convention C (for example) 20034has no effect. 20035 20036There are four exceptions to this general rule: 20037 20038 20039@itemize * 20040 20041@item 20042@emph{Convention Fortran and array subtypes}. 20043 20044If pragma Convention Fortran is specified for an array subtype, then in 20045accordance with the implementation advice in section 3.6.2(11) of the 20046Ada Reference Manual, the array will be stored in a Fortran-compatible 20047column-major manner, instead of the normal default row-major order. 20048 20049@item 20050@emph{Convention C and enumeration types} 20051 20052GNAT normally stores enumeration types in 8, 16, or 32 bits as required 20053to accommodate all values of the type. For example, for the enumeration 20054type declared by: 20055 20056@example 20057type Color is (Red, Green, Blue); 20058@end example 20059 200608 bits is sufficient to store all values of the type, so by default, objects 20061of type @code{Color} will be represented using 8 bits. However, normal C 20062convention is to use 32 bits for all enum values in C, since enum values 20063are essentially of type int. If pragma @code{Convention C} is specified for an 20064Ada enumeration type, then the size is modified as necessary (usually to 2006532 bits) to be consistent with the C convention for enum values. 20066 20067Note that this treatment applies only to types. If Convention C is given for 20068an enumeration object, where the enumeration type is not Convention C, then 20069Object_Size bits are allocated. For example, for a normal enumeration type, 20070with less than 256 elements, only 8 bits will be allocated for the object. 20071Since this may be a surprise in terms of what C expects, GNAT will issue a 20072warning in this situation. The warning can be suppressed by giving an explicit 20073size clause specifying the desired size. 20074 20075@item 20076@emph{Convention C/Fortran and Boolean types} 20077 20078In C, the usual convention for boolean values, that is values used for 20079conditions, is that zero represents false, and nonzero values represent 20080true. In Ada, the normal convention is that two specific values, typically 200810/1, are used to represent false/true respectively. 20082 20083Fortran has a similar convention for @code{LOGICAL} values (any nonzero 20084value represents true). 20085 20086To accommodate the Fortran and C conventions, if a pragma Convention specifies 20087C or Fortran convention for a derived Boolean, as in the following example: 20088 20089@example 20090type C_Switch is new Boolean; 20091pragma Convention (C, C_Switch); 20092@end example 20093 20094then the GNAT generated code will treat any nonzero value as true. For truth 20095values generated by GNAT, the conventional value 1 will be used for True, but 20096when one of these values is read, any nonzero value is treated as True. 20097@end itemize 20098 20099@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 20100@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{290}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{291} 20101@section Conventions and Anonymous Access Types 20102 20103 20104@geindex Anonymous access types 20105 20106@geindex Convention for anonymous access types 20107 20108The RM is not entirely clear on convention handling in a number of cases, 20109and in particular, it is not clear on the convention to be given to 20110anonymous access types in general, and in particular what is to be 20111done for the case of anonymous access-to-subprogram. 20112 20113In GNAT, we decide that if an explicit Convention is applied 20114to an object or component, and its type is such an anonymous type, 20115then the convention will apply to this anonymous type as well. This 20116seems to make sense since it is anomolous in any case to have a 20117different convention for an object and its type, and there is clearly 20118no way to explicitly specify a convention for an anonymous type, since 20119it doesn't have a name to specify! 20120 20121Furthermore, we decide that if a convention is applied to a record type, 20122then this convention is inherited by any of its components that are of an 20123anonymous access type which do not have an explicitly specified convention. 20124 20125The following program shows these conventions in action: 20126 20127@example 20128package ConvComp is 20129 type Foo is range 1 .. 10; 20130 type T1 is record 20131 A : access function (X : Foo) return Integer; 20132 B : Integer; 20133 end record; 20134 pragma Convention (C, T1); 20135 20136 type T2 is record 20137 A : access function (X : Foo) return Integer; 20138 pragma Convention (C, A); 20139 B : Integer; 20140 end record; 20141 pragma Convention (COBOL, T2); 20142 20143 type T3 is record 20144 A : access function (X : Foo) return Integer; 20145 pragma Convention (COBOL, A); 20146 B : Integer; 20147 end record; 20148 pragma Convention (C, T3); 20149 20150 type T4 is record 20151 A : access function (X : Foo) return Integer; 20152 B : Integer; 20153 end record; 20154 pragma Convention (COBOL, T4); 20155 20156 function F (X : Foo) return Integer; 20157 pragma Convention (C, F); 20158 20159 function F (X : Foo) return Integer is (13); 20160 20161 TV1 : T1 := (F'Access, 12); -- OK 20162 TV2 : T2 := (F'Access, 13); -- OK 20163 20164 TV3 : T3 := (F'Access, 13); -- ERROR 20165 | 20166>>> subprogram "F" has wrong convention 20167>>> does not match access to subprogram declared at line 17 20168 38. TV4 : T4 := (F'Access, 13); -- ERROR 20169 | 20170>>> subprogram "F" has wrong convention 20171>>> does not match access to subprogram declared at line 24 20172 39. end ConvComp; 20173@end example 20174 20175@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 20176@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{292}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{293} 20177@section Determining the Representations chosen by GNAT 20178 20179 20180@geindex Representation 20181@geindex determination of 20182 20183@geindex -gnatR (gcc) 20184 20185Although the descriptions in this section are intended to be complete, it is 20186often easier to simply experiment to see what GNAT accepts and what the 20187effect is on the layout of types and objects. 20188 20189As required by the Ada RM, if a representation clause is not accepted, then 20190it must be rejected as illegal by the compiler. However, when a 20191representation clause or pragma is accepted, there can still be questions 20192of what the compiler actually does. For example, if a partial record 20193representation clause specifies the location of some components and not 20194others, then where are the non-specified components placed? Or if pragma 20195@code{Pack} is used on a record, then exactly where are the resulting 20196fields placed? The section on pragma @code{Pack} in this chapter can be 20197used to answer the second question, but it is often easier to just see 20198what the compiler does. 20199 20200For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 20201with this option, then the compiler will output information on the actual 20202representations chosen, in a format similar to source representation 20203clauses. For example, if we compile the package: 20204 20205@example 20206package q is 20207 type r (x : boolean) is tagged record 20208 case x is 20209 when True => S : String (1 .. 100); 20210 when False => null; 20211 end case; 20212 end record; 20213 20214 type r2 is new r (false) with record 20215 y2 : integer; 20216 end record; 20217 20218 for r2 use record 20219 y2 at 16 range 0 .. 31; 20220 end record; 20221 20222 type x is record 20223 y : character; 20224 end record; 20225 20226 type x1 is array (1 .. 10) of x; 20227 for x1'component_size use 11; 20228 20229 type ia is access integer; 20230 20231 type Rb1 is array (1 .. 13) of Boolean; 20232 pragma Pack (rb1); 20233 20234 type Rb2 is array (1 .. 65) of Boolean; 20235 pragma Pack (rb2); 20236 20237 type x2 is record 20238 l1 : Boolean; 20239 l2 : Duration; 20240 l3 : Float; 20241 l4 : Boolean; 20242 l5 : Rb1; 20243 l6 : Rb2; 20244 end record; 20245 pragma Pack (x2); 20246end q; 20247@end example 20248 20249using the switch @emph{-gnatR} we obtain the following output: 20250 20251@example 20252Representation information for unit q 20253------------------------------------- 20254 20255for r'Size use ??; 20256for r'Alignment use 4; 20257for r use record 20258 x at 4 range 0 .. 7; 20259 _tag at 0 range 0 .. 31; 20260 s at 5 range 0 .. 799; 20261end record; 20262 20263for r2'Size use 160; 20264for r2'Alignment use 4; 20265for r2 use record 20266 x at 4 range 0 .. 7; 20267 _tag at 0 range 0 .. 31; 20268 _parent at 0 range 0 .. 63; 20269 y2 at 16 range 0 .. 31; 20270end record; 20271 20272for x'Size use 8; 20273for x'Alignment use 1; 20274for x use record 20275 y at 0 range 0 .. 7; 20276end record; 20277 20278for x1'Size use 112; 20279for x1'Alignment use 1; 20280for x1'Component_Size use 11; 20281 20282for rb1'Size use 13; 20283for rb1'Alignment use 2; 20284for rb1'Component_Size use 1; 20285 20286for rb2'Size use 72; 20287for rb2'Alignment use 1; 20288for rb2'Component_Size use 1; 20289 20290for x2'Size use 224; 20291for x2'Alignment use 4; 20292for x2 use record 20293 l1 at 0 range 0 .. 0; 20294 l2 at 0 range 1 .. 64; 20295 l3 at 12 range 0 .. 31; 20296 l4 at 16 range 0 .. 0; 20297 l5 at 16 range 1 .. 13; 20298 l6 at 18 range 0 .. 71; 20299end record; 20300@end example 20301 20302The Size values are actually the Object_Size, i.e., the default size that 20303will be allocated for objects of the type. 20304The @code{??} size for type r indicates that we have a variant record, and the 20305actual size of objects will depend on the discriminant value. 20306 20307The Alignment values show the actual alignment chosen by the compiler 20308for each record or array type. 20309 20310The record representation clause for type r shows where all fields 20311are placed, including the compiler generated tag field (whose location 20312cannot be controlled by the programmer). 20313 20314The record representation clause for the type extension r2 shows all the 20315fields present, including the parent field, which is a copy of the fields 20316of the parent type of r2, i.e., r1. 20317 20318The component size and size clauses for types rb1 and rb2 show 20319the exact effect of pragma @code{Pack} on these arrays, and the record 20320representation clause for type x2 shows how pragma @cite{Pack} affects 20321this record type. 20322 20323In some cases, it may be useful to cut and paste the representation clauses 20324generated by the compiler into the original source to fix and guarantee 20325the actual representation to be used. 20326 20327@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 20328@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{294}@anchor{gnat_rm/standard_library_routines id1}@anchor{295} 20329@chapter Standard Library Routines 20330 20331 20332The Ada Reference Manual contains in Annex A a full description of an 20333extensive set of standard library routines that can be used in any Ada 20334program, and which must be provided by all Ada compilers. They are 20335analogous to the standard C library used by C programs. 20336 20337GNAT implements all of the facilities described in annex A, and for most 20338purposes the description in the Ada Reference Manual, or appropriate Ada 20339text book, will be sufficient for making use of these facilities. 20340 20341In the case of the input-output facilities, 20342@ref{f,,The Implementation of Standard I/O}, 20343gives details on exactly how GNAT interfaces to the 20344file system. For the remaining packages, the Ada Reference Manual 20345should be sufficient. The following is a list of the packages included, 20346together with a brief description of the functionality that is provided. 20347 20348For completeness, references are included to other predefined library 20349routines defined in other sections of the Ada Reference Manual (these are 20350cross-indexed from Annex A). For further details see the relevant 20351package declarations in the run-time library. In particular, a few units 20352are not implemented, as marked by the presence of pragma Unimplemented_Unit, 20353and in this case the package declaration contains comments explaining why 20354the unit is not implemented. 20355 20356 20357@table @asis 20358 20359@item @code{Ada} @emph{(A.2)} 20360 20361This is a parent package for all the standard library packages. It is 20362usually included implicitly in your program, and itself contains no 20363useful data or routines. 20364 20365@item @code{Ada.Assertions} @emph{(11.4.2)} 20366 20367@code{Assertions} provides the @code{Assert} subprograms, and also 20368the declaration of the @code{Assertion_Error} exception. 20369 20370@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 20371 20372@code{Asynchronous_Task_Control} provides low level facilities for task 20373synchronization. It is typically not implemented. See package spec for details. 20374 20375@item @code{Ada.Calendar} @emph{(9.6)} 20376 20377@code{Calendar} provides time of day access, and routines for 20378manipulating times and durations. 20379 20380@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 20381 20382This package provides additional arithmetic 20383operations for @code{Calendar}. 20384 20385@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 20386 20387This package provides formatting operations for @code{Calendar}. 20388 20389@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 20390 20391This package provides additional @code{Calendar} facilities 20392for handling time zones. 20393 20394@item @code{Ada.Characters} @emph{(A.3.1)} 20395 20396This is a dummy parent package that contains no useful entities 20397 20398@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 20399 20400This package provides character conversion functions. 20401 20402@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 20403 20404This package provides some basic character handling capabilities, 20405including classification functions for classes of characters (e.g., test 20406for letters, or digits). 20407 20408@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 20409 20410This package includes a complete set of definitions of the characters 20411that appear in type CHARACTER. It is useful for writing programs that 20412will run in international environments. For example, if you want an 20413upper case E with an acute accent in a string, it is often better to use 20414the definition of @code{UC_E_Acute} in this package. Then your program 20415will print in an understandable manner even if your environment does not 20416support these extended characters. 20417 20418@item @code{Ada.Command_Line} @emph{(A.15)} 20419 20420This package provides access to the command line parameters and the name 20421of the current program (analogous to the use of @code{argc} and @code{argv} 20422in C), and also allows the exit status for the program to be set in a 20423system-independent manner. 20424 20425@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20426 20427This package provides text input and output of complex numbers. 20428 20429@item @code{Ada.Containers} @emph{(A.18.1)} 20430 20431A top level package providing a few basic definitions used by all the 20432following specific child packages that provide specific kinds of 20433containers. 20434@end table 20435 20436@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20437 20438@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20439 20440@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20441 20442@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20443 20444@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20445 20446@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20447 20448@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20449 20450@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20451 20452@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20453 20454@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20455 20456@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20457 20458@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20459 20460@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20461 20462@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20463 20464@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20465 20466@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20467 20468@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20469 20470@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20471 20472@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20473 20474@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20475 20476@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20477 20478@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20479 20480@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20481 20482 20483@table @asis 20484 20485@item @code{Ada.Directories} @emph{(A.16)} 20486 20487This package provides operations on directories. 20488 20489@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20490 20491This package provides additional directory operations handling 20492hiearchical file names. 20493 20494@item @code{Ada.Directories.Information} @emph{(A.16)} 20495 20496This is an implementation defined package for additional directory 20497operations, which is not implemented in GNAT. 20498 20499@item @code{Ada.Decimal} @emph{(F.2)} 20500 20501This package provides constants describing the range of decimal numbers 20502implemented, and also a decimal divide routine (analogous to the COBOL 20503verb DIVIDE ... GIVING ... REMAINDER ...) 20504 20505@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20506 20507This package provides input-output using a model of a set of records of 20508fixed-length, containing an arbitrary definite Ada type, indexed by an 20509integer record number. 20510 20511@item @code{Ada.Dispatching} @emph{(D.2.1)} 20512 20513A parent package containing definitions for task dispatching operations. 20514 20515@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20516 20517Not implemented in GNAT. 20518 20519@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20520 20521Not implemented in GNAT. 20522 20523@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20524 20525Not implemented in GNAT. 20526 20527@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20528 20529This package allows the priorities of a task to be adjusted dynamically 20530as the task is running. 20531 20532@item @code{Ada.Environment_Variables} @emph{(A.17)} 20533 20534This package provides facilities for accessing environment variables. 20535 20536@item @code{Ada.Exceptions} @emph{(11.4.1)} 20537 20538This package provides additional information on exceptions, and also 20539contains facilities for treating exceptions as data objects, and raising 20540exceptions with associated messages. 20541 20542@item @code{Ada.Execution_Time} @emph{(D.14)} 20543 20544This package provides CPU clock functionalities. It is not implemented on 20545all targets (see package spec for details). 20546 20547@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20548 20549Not implemented in GNAT. 20550 20551@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'} 20552 20553Not implemented in GNAT. 20554 20555@item @code{Ada.Finalization} @emph{(7.6)} 20556 20557This package contains the declarations and subprograms to support the 20558use of controlled types, providing for automatic initialization and 20559finalization (analogous to the constructors and destructors of C++). 20560 20561@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20562 20563A library level instantiation of Text_IO.Float_IO for type Float. 20564 20565@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 20566 20567A library level instantiation of Wide_Text_IO.Float_IO for type Float. 20568 20569@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 20570 20571A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 20572 20573@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 20574 20575A library level instantiation of Text_IO.Integer_IO for type Integer. 20576 20577@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 20578 20579A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 20580 20581@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 20582 20583A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 20584 20585@item @code{Ada.Interrupts} @emph{(C.3.2)} 20586 20587This package provides facilities for interfacing to interrupts, which 20588includes the set of signals or conditions that can be raised and 20589recognized as interrupts. 20590 20591@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 20592 20593This package provides the set of interrupt names (actually signal 20594or condition names) that can be handled by GNAT. 20595 20596@item @code{Ada.IO_Exceptions} @emph{(A.13)} 20597 20598This package defines the set of exceptions that can be raised by use of 20599the standard IO packages. 20600 20601@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 20602 20603This package provides a generic interface to generalized iterators. 20604 20605@item @code{Ada.Locales} @emph{(A.19)} 20606 20607This package provides declarations providing information (Language 20608and Country) about the current locale. This package is currently not 20609implemented other than by providing stubs which will always return 20610Language_Unknown/Country_Unknown. 20611 20612@item @code{Ada.Numerics} 20613 20614This package contains some standard constants and exceptions used 20615throughout the numerics packages. Note that the constants pi and e are 20616defined here, and it is better to use these definitions than rolling 20617your own. 20618 20619@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 20620 20621Provides operations on arrays of complex numbers. 20622 20623@item @code{Ada.Numerics.Complex_Elementary_Functions} 20624 20625Provides the implementation of standard elementary functions (such as 20626log and trigonometric functions) operating on complex numbers using the 20627standard @code{Float} and the @code{Complex} and @code{Imaginary} types 20628created by the package @code{Numerics.Complex_Types}. 20629 20630@item @code{Ada.Numerics.Complex_Types} 20631 20632This is a predefined instantiation of 20633@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 20634build the type @code{Complex} and @code{Imaginary}. 20635 20636@item @code{Ada.Numerics.Discrete_Random} 20637 20638This generic package provides a random number generator suitable for generating 20639uniformly distributed values of a specified discrete subtype. 20640 20641@item @code{Ada.Numerics.Float_Random} 20642 20643This package provides a random number generator suitable for generating 20644uniformly distributed floating point values in the unit interval. 20645 20646@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 20647 20648This is a generic version of the package that provides the 20649implementation of standard elementary functions (such as log and 20650trigonometric functions) for an arbitrary complex type. 20651 20652The following predefined instantiations of this package are provided: 20653 20654 20655@itemize * 20656 20657@item 20658@code{Short_Float} 20659 20660@code{Ada.Numerics.Short_Complex_Elementary_Functions} 20661 20662@item 20663@code{Float} 20664 20665@code{Ada.Numerics.Complex_Elementary_Functions} 20666 20667@item 20668@code{Long_Float} 20669 20670@code{Ada.Numerics.Long_Complex_Elementary_Functions} 20671@end itemize 20672 20673@item @code{Ada.Numerics.Generic_Complex_Types} 20674 20675This is a generic package that allows the creation of complex types, 20676with associated complex arithmetic operations. 20677 20678The following predefined instantiations of this package exist 20679 20680 20681@itemize * 20682 20683@item 20684@code{Short_Float} 20685 20686@code{Ada.Numerics.Short_Complex_Complex_Types} 20687 20688@item 20689@code{Float} 20690 20691@code{Ada.Numerics.Complex_Complex_Types} 20692 20693@item 20694@code{Long_Float} 20695 20696@code{Ada.Numerics.Long_Complex_Complex_Types} 20697@end itemize 20698 20699@item @code{Ada.Numerics.Generic_Elementary_Functions} 20700 20701This is a generic package that provides the implementation of standard 20702elementary functions (such as log an trigonometric functions) for an 20703arbitrary float type. 20704 20705The following predefined instantiations of this package exist 20706 20707 20708@itemize * 20709 20710@item 20711@code{Short_Float} 20712 20713@code{Ada.Numerics.Short_Elementary_Functions} 20714 20715@item 20716@code{Float} 20717 20718@code{Ada.Numerics.Elementary_Functions} 20719 20720@item 20721@code{Long_Float} 20722 20723@code{Ada.Numerics.Long_Elementary_Functions} 20724@end itemize 20725 20726@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 20727 20728Generic operations on arrays of reals 20729 20730@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 20731 20732Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 20733 20734@item @code{Ada.Real_Time} @emph{(D.8)} 20735 20736This package provides facilities similar to those of @code{Calendar}, but 20737operating with a finer clock suitable for real time control. Note that 20738annex D requires that there be no backward clock jumps, and GNAT generally 20739guarantees this behavior, but of course if the external clock on which 20740the GNAT runtime depends is deliberately reset by some external event, 20741then such a backward jump may occur. 20742 20743@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 20744 20745Not implemented in GNAT. 20746 20747@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 20748 20749This package provides input-output facilities for sequential files, 20750which can contain a sequence of values of a single type, which can be 20751any Ada type, including indefinite (unconstrained) types. 20752 20753@item @code{Ada.Storage_IO} @emph{(A.9)} 20754 20755This package provides a facility for mapping arbitrary Ada types to and 20756from a storage buffer. It is primarily intended for the creation of new 20757IO packages. 20758 20759@item @code{Ada.Streams} @emph{(13.13.1)} 20760 20761This is a generic package that provides the basic support for the 20762concept of streams as used by the stream attributes (@code{Input}, 20763@code{Output}, @code{Read} and @code{Write}). 20764 20765@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 20766 20767This package is a specialization of the type @code{Streams} defined in 20768package @code{Streams} together with a set of operations providing 20769Stream_IO capability. The Stream_IO model permits both random and 20770sequential access to a file which can contain an arbitrary set of values 20771of one or more Ada types. 20772 20773@item @code{Ada.Strings} @emph{(A.4.1)} 20774 20775This package provides some basic constants used by the string handling 20776packages. 20777 20778@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 20779 20780This package provides facilities for handling variable length 20781strings. The bounded model requires a maximum length. It is thus 20782somewhat more limited than the unbounded model, but avoids the use of 20783dynamic allocation or finalization. 20784 20785@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20786 20787Provides case-insensitive comparisons of bounded strings 20788 20789@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 20790 20791This package provides a generic hash function for bounded strings 20792 20793@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20794 20795This package provides a generic hash function for bounded strings that 20796converts the string to be hashed to lower case. 20797 20798@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 20799 20800This package provides a comparison function for bounded strings that works 20801in a case insensitive manner by converting to lower case before the comparison. 20802 20803@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 20804 20805This package provides facilities for handling fixed length strings. 20806 20807@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 20808 20809This package provides an equality function for fixed strings that compares 20810the strings after converting both to lower case. 20811 20812@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 20813 20814This package provides a case insensitive hash function for fixed strings that 20815converts the string to lower case before computing the hash. 20816 20817@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 20818 20819This package provides a comparison function for fixed strings that works 20820in a case insensitive manner by converting to lower case before the comparison. 20821 20822@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 20823 20824This package provides a hash function for strings. 20825 20826@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 20827 20828This package provides a hash function for strings that is case insensitive. 20829The string is converted to lower case before computing the hash. 20830 20831@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 20832 20833This package provides a comparison function for\strings that works 20834in a case insensitive manner by converting to lower case before the comparison. 20835 20836@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 20837 20838This package provides facilities for handling character mappings and 20839arbitrarily defined subsets of characters. For instance it is useful in 20840defining specialized translation tables. 20841 20842@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 20843 20844This package provides a standard set of predefined mappings and 20845predefined character sets. For example, the standard upper to lower case 20846conversion table is found in this package. Note that upper to lower case 20847conversion is non-trivial if you want to take the entire set of 20848characters, including extended characters like E with an acute accent, 20849into account. You should use the mappings in this package (rather than 20850adding 32 yourself) to do case mappings. 20851 20852@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 20853 20854This package provides facilities for handling variable length 20855strings. The unbounded model allows arbitrary length strings, but 20856requires the use of dynamic allocation and finalization. 20857 20858@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20859 20860Provides case-insensitive comparisons of unbounded strings 20861 20862@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 20863 20864This package provides a generic hash function for unbounded strings 20865 20866@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20867 20868This package provides a generic hash function for unbounded strings that 20869converts the string to be hashed to lower case. 20870 20871@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 20872 20873This package provides a comparison function for unbounded strings that works 20874in a case insensitive manner by converting to lower case before the comparison. 20875 20876@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 20877 20878This package provides basic definitions for dealing with UTF-encoded strings. 20879 20880@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 20881 20882This package provides conversion functions for UTF-encoded strings. 20883@end table 20884 20885@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 20886 20887@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 20888 20889 20890@table @asis 20891 20892@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 20893 20894These packages provide facilities for handling UTF encodings for 20895Strings, Wide_Strings and Wide_Wide_Strings. 20896@end table 20897 20898@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 20899 20900@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 20901 20902@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 20903 20904 20905@table @asis 20906 20907@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 20908 20909These packages provide analogous capabilities to the corresponding 20910packages without @code{Wide_} in the name, but operate with the types 20911@code{Wide_String} and @code{Wide_Character} instead of @code{String} 20912and @code{Character}. Versions of all the child packages are available. 20913@end table 20914 20915@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 20916 20917@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 20918 20919@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 20920 20921 20922@table @asis 20923 20924@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 20925 20926These packages provide analogous capabilities to the corresponding 20927packages without @code{Wide_} in the name, but operate with the types 20928@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 20929of @code{String} and @code{Character}. 20930 20931@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 20932 20933This package provides facilities for synchronizing tasks at a low level 20934with barriers. 20935 20936@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 20937 20938This package provides some standard facilities for controlling task 20939communication in a synchronous manner. 20940 20941@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 20942 20943Not implemented in GNAT. 20944 20945@item @code{Ada.Tags} 20946 20947This package contains definitions for manipulation of the tags of tagged 20948values. 20949 20950@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 20951 20952This package provides a way of constructing tagged class-wide values given 20953only the tag value. 20954 20955@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 20956 20957This package provides the capability of associating arbitrary 20958task-specific data with separate tasks. 20959 20960@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 20961 20962This package provides capabilities for task identification. 20963 20964@item @code{Ada.Task_Termination} @emph{(C.7.3)} 20965 20966This package provides control over task termination. 20967 20968@item @code{Ada.Text_IO} 20969 20970This package provides basic text input-output capabilities for 20971character, string and numeric data. The subpackages of this 20972package are listed next. Note that although these are defined 20973as subpackages in the RM, they are actually transparently 20974implemented as child packages in GNAT, meaning that they 20975are only loaded if needed. 20976 20977@item @code{Ada.Text_IO.Decimal_IO} 20978 20979Provides input-output facilities for decimal fixed-point types 20980 20981@item @code{Ada.Text_IO.Enumeration_IO} 20982 20983Provides input-output facilities for enumeration types. 20984 20985@item @code{Ada.Text_IO.Fixed_IO} 20986 20987Provides input-output facilities for ordinary fixed-point types. 20988 20989@item @code{Ada.Text_IO.Float_IO} 20990 20991Provides input-output facilities for float types. The following 20992predefined instantiations of this generic package are available: 20993 20994 20995@itemize * 20996 20997@item 20998@code{Short_Float} 20999 21000@code{Short_Float_Text_IO} 21001 21002@item 21003@code{Float} 21004 21005@code{Float_Text_IO} 21006 21007@item 21008@code{Long_Float} 21009 21010@code{Long_Float_Text_IO} 21011@end itemize 21012 21013@item @code{Ada.Text_IO.Integer_IO} 21014 21015Provides input-output facilities for integer types. The following 21016predefined instantiations of this generic package are available: 21017 21018 21019@itemize * 21020 21021@item 21022@code{Short_Short_Integer} 21023 21024@code{Ada.Short_Short_Integer_Text_IO} 21025 21026@item 21027@code{Short_Integer} 21028 21029@code{Ada.Short_Integer_Text_IO} 21030 21031@item 21032@code{Integer} 21033 21034@code{Ada.Integer_Text_IO} 21035 21036@item 21037@code{Long_Integer} 21038 21039@code{Ada.Long_Integer_Text_IO} 21040 21041@item 21042@code{Long_Long_Integer} 21043 21044@code{Ada.Long_Long_Integer_Text_IO} 21045@end itemize 21046 21047@item @code{Ada.Text_IO.Modular_IO} 21048 21049Provides input-output facilities for modular (unsigned) types. 21050 21051@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 21052 21053Provides input-output facilities for bounded strings. 21054 21055@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 21056 21057This package provides basic text input-output capabilities for complex 21058data. 21059 21060@item @code{Ada.Text_IO.Editing (F.3.3)} 21061 21062This package contains routines for edited output, analogous to the use 21063of pictures in COBOL. The picture formats used by this package are a 21064close copy of the facility in COBOL. 21065 21066@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 21067 21068This package provides a facility that allows Text_IO files to be treated 21069as streams, so that the stream attributes can be used for writing 21070arbitrary data, including binary data, to Text_IO files. 21071 21072@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 21073 21074This package provides input-output facilities for unbounded strings. 21075 21076@item @code{Ada.Unchecked_Conversion (13.9)} 21077 21078This generic package allows arbitrary conversion from one type to 21079another of the same size, providing for breaking the type safety in 21080special circumstances. 21081 21082If the types have the same Size (more accurately the same Value_Size), 21083then the effect is simply to transfer the bits from the source to the 21084target type without any modification. This usage is well defined, and 21085for simple types whose representation is typically the same across 21086all implementations, gives a portable method of performing such 21087conversions. 21088 21089If the types do not have the same size, then the result is implementation 21090defined, and thus may be non-portable. The following describes how GNAT 21091handles such unchecked conversion cases. 21092 21093If the types are of different sizes, and are both discrete types, then 21094the effect is of a normal type conversion without any constraint checking. 21095In particular if the result type has a larger size, the result will be 21096zero or sign extended. If the result type has a smaller size, the result 21097will be truncated by ignoring high order bits. 21098 21099If the types are of different sizes, and are not both discrete types, 21100then the conversion works as though pointers were created to the source 21101and target, and the pointer value is converted. The effect is that bits 21102are copied from successive low order storage units and bits of the source 21103up to the length of the target type. 21104 21105A warning is issued if the lengths differ, since the effect in this 21106case is implementation dependent, and the above behavior may not match 21107that of some other compiler. 21108 21109A pointer to one type may be converted to a pointer to another type using 21110unchecked conversion. The only case in which the effect is undefined is 21111when one or both pointers are pointers to unconstrained array types. In 21112this case, the bounds information may get incorrectly transferred, and in 21113particular, GNAT uses double size pointers for such types, and it is 21114meaningless to convert between such pointer types. GNAT will issue a 21115warning if the alignment of the target designated type is more strict 21116than the alignment of the source designated type (since the result may 21117be unaligned in this case). 21118 21119A pointer other than a pointer to an unconstrained array type may be 21120converted to and from System.Address. Such usage is common in Ada 83 21121programs, but note that Ada.Address_To_Access_Conversions is the 21122preferred method of performing such conversions in Ada 95 and Ada 2005. 21123Neither 21124unchecked conversion nor Ada.Address_To_Access_Conversions should be 21125used in conjunction with pointers to unconstrained objects, since 21126the bounds information cannot be handled correctly in this case. 21127 21128@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 21129 21130This generic package allows explicit freeing of storage previously 21131allocated by use of an allocator. 21132 21133@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 21134 21135This package is similar to @code{Ada.Text_IO}, except that the external 21136file supports wide character representations, and the internal types are 21137@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21138and @code{String}. The corresponding set of nested packages and child 21139packages are defined. 21140 21141@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 21142 21143This package is similar to @code{Ada.Text_IO}, except that the external 21144file supports wide character representations, and the internal types are 21145@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21146and @code{String}. The corresponding set of nested packages and child 21147packages are defined. 21148@end table 21149 21150For packages in Interfaces and System, all the RM defined packages are 21151available in GNAT, see the Ada 2012 RM for full details. 21152 21153@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 21154@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{296}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{297} 21155@chapter The Implementation of Standard I/O 21156 21157 21158GNAT implements all the required input-output facilities described in 21159A.6 through A.14. These sections of the Ada Reference Manual describe the 21160required behavior of these packages from the Ada point of view, and if 21161you are writing a portable Ada program that does not need to know the 21162exact manner in which Ada maps to the outside world when it comes to 21163reading or writing external files, then you do not need to read this 21164chapter. As long as your files are all regular files (not pipes or 21165devices), and as long as you write and read the files only from Ada, the 21166description in the Ada Reference Manual is sufficient. 21167 21168However, if you want to do input-output to pipes or other devices, such 21169as the keyboard or screen, or if the files you are dealing with are 21170either generated by some other language, or to be read by some other 21171language, then you need to know more about the details of how the GNAT 21172implementation of these input-output facilities behaves. 21173 21174In this chapter we give a detailed description of exactly how GNAT 21175interfaces to the file system. As always, the sources of the system are 21176available to you for answering questions at an even more detailed level, 21177but for most purposes the information in this chapter will suffice. 21178 21179Another reason that you may need to know more about how input-output is 21180implemented arises when you have a program written in mixed languages 21181where, for example, files are shared between the C and Ada sections of 21182the same program. GNAT provides some additional facilities, in the form 21183of additional child library packages, that facilitate this sharing, and 21184these additional facilities are also described in this chapter. 21185 21186@menu 21187* Standard I/O Packages:: 21188* FORM Strings:: 21189* Direct_IO:: 21190* Sequential_IO:: 21191* Text_IO:: 21192* Wide_Text_IO:: 21193* Wide_Wide_Text_IO:: 21194* Stream_IO:: 21195* Text Translation:: 21196* Shared Files:: 21197* Filenames encoding:: 21198* File content encoding:: 21199* Open Modes:: 21200* Operations on C Streams:: 21201* Interfacing to C Streams:: 21202 21203@end menu 21204 21205@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 21206@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{298}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{299} 21207@section Standard I/O Packages 21208 21209 21210The Standard I/O packages described in Annex A for 21211 21212 21213@itemize * 21214 21215@item 21216Ada.Text_IO 21217 21218@item 21219Ada.Text_IO.Complex_IO 21220 21221@item 21222Ada.Text_IO.Text_Streams 21223 21224@item 21225Ada.Wide_Text_IO 21226 21227@item 21228Ada.Wide_Text_IO.Complex_IO 21229 21230@item 21231Ada.Wide_Text_IO.Text_Streams 21232 21233@item 21234Ada.Wide_Wide_Text_IO 21235 21236@item 21237Ada.Wide_Wide_Text_IO.Complex_IO 21238 21239@item 21240Ada.Wide_Wide_Text_IO.Text_Streams 21241 21242@item 21243Ada.Stream_IO 21244 21245@item 21246Ada.Sequential_IO 21247 21248@item 21249Ada.Direct_IO 21250@end itemize 21251 21252are implemented using the C 21253library streams facility; where 21254 21255 21256@itemize * 21257 21258@item 21259All files are opened using @code{fopen}. 21260 21261@item 21262All input/output operations use @code{fread}/@cite{fwrite}. 21263@end itemize 21264 21265There is no internal buffering of any kind at the Ada library level. The only 21266buffering is that provided at the system level in the implementation of the 21267library routines that support streams. This facilitates shared use of these 21268streams by mixed language programs. Note though that system level buffering is 21269explicitly enabled at elaboration of the standard I/O packages and that can 21270have an impact on mixed language programs, in particular those using I/O before 21271calling the Ada elaboration routine (e.g., adainit). It is recommended to call 21272the Ada elaboration routine before performing any I/O or when impractical, 21273flush the common I/O streams and in particular Standard_Output before 21274elaborating the Ada code. 21275 21276@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 21277@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{29a}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{29b} 21278@section FORM Strings 21279 21280 21281The format of a FORM string in GNAT is: 21282 21283@example 21284"keyword=value,keyword=value,...,keyword=value" 21285@end example 21286 21287where letters may be in upper or lower case, and there are no spaces 21288between values. The order of the entries is not important. Currently 21289the following keywords defined. 21290 21291@example 21292TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 21293SHARED=[YES|NO] 21294WCEM=[n|h|u|s|e|8|b] 21295ENCODING=[UTF8|8BITS] 21296@end example 21297 21298The use of these parameters is described later in this section. If an 21299unrecognized keyword appears in a form string, it is silently ignored 21300and not considered invalid. 21301 21302@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 21303@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{29c}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{29d} 21304@section Direct_IO 21305 21306 21307Direct_IO can only be instantiated for definite types. This is a 21308restriction of the Ada language, which means that the records are fixed 21309length (the length being determined by @code{type'Size}, rounded 21310up to the next storage unit boundary if necessary). 21311 21312The records of a Direct_IO file are simply written to the file in index 21313sequence, with the first record starting at offset zero, and subsequent 21314records following. There is no control information of any kind. For 21315example, if 32-bit integers are being written, each record takes 213164-bytes, so the record at index @code{K} starts at offset 21317(@code{K}-1)*4. 21318 21319There is no limit on the size of Direct_IO files, they are expanded as 21320necessary to accommodate whatever records are written to the file. 21321 21322@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 21323@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{29e}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{29f} 21324@section Sequential_IO 21325 21326 21327Sequential_IO may be instantiated with either a definite (constrained) 21328or indefinite (unconstrained) type. 21329 21330For the definite type case, the elements written to the file are simply 21331the memory images of the data values with no control information of any 21332kind. The resulting file should be read using the same type, no validity 21333checking is performed on input. 21334 21335For the indefinite type case, the elements written consist of two 21336parts. First is the size of the data item, written as the memory image 21337of a @code{Interfaces.C.size_t} value, followed by the memory image of 21338the data value. The resulting file can only be read using the same 21339(unconstrained) type. Normal assignment checks are performed on these 21340read operations, and if these checks fail, @code{Data_Error} is 21341raised. In particular, in the array case, the lengths must match, and in 21342the variant record case, if the variable for a particular read operation 21343is constrained, the discriminants must match. 21344 21345Note that it is not possible to use Sequential_IO to write variable 21346length array items, and then read the data back into different length 21347arrays. For example, the following will raise @code{Data_Error}: 21348 21349@example 21350package IO is new Sequential_IO (String); 21351F : IO.File_Type; 21352S : String (1..4); 21353... 21354IO.Create (F) 21355IO.Write (F, "hello!") 21356IO.Reset (F, Mode=>In_File); 21357IO.Read (F, S); 21358Put_Line (S); 21359@end example 21360 21361On some Ada implementations, this will print @code{hell}, but the program is 21362clearly incorrect, since there is only one element in the file, and that 21363element is the string @code{hello!}. 21364 21365In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 21366using Stream_IO, and this is the preferred mechanism. In particular, the 21367above program fragment rewritten to use Stream_IO will work correctly. 21368 21369@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 21370@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2a0}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2a1} 21371@section Text_IO 21372 21373 21374Text_IO files consist of a stream of characters containing the following 21375special control characters: 21376 21377@example 21378LF (line feed, 16#0A#) Line Mark 21379FF (form feed, 16#0C#) Page Mark 21380@end example 21381 21382A canonical Text_IO file is defined as one in which the following 21383conditions are met: 21384 21385 21386@itemize * 21387 21388@item 21389The character @code{LF} is used only as a line mark, i.e., to mark the end 21390of the line. 21391 21392@item 21393The character @code{FF} is used only as a page mark, i.e., to mark the 21394end of a page and consequently can appear only immediately following a 21395@code{LF} (line mark) character. 21396 21397@item 21398The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} 21399(line mark, page mark). In the former case, the page mark is implicitly 21400assumed to be present. 21401@end itemize 21402 21403A file written using Text_IO will be in canonical form provided that no 21404explicit @code{LF} or @code{FF} characters are written using @code{Put} 21405or @code{Put_Line}. There will be no @code{FF} character at the end of 21406the file unless an explicit @code{New_Page} operation was performed 21407before closing the file. 21408 21409A canonical Text_IO file that is a regular file (i.e., not a device or a 21410pipe) can be read using any of the routines in Text_IO. The 21411semantics in this case will be exactly as defined in the Ada Reference 21412Manual, and all the routines in Text_IO are fully implemented. 21413 21414A text file that does not meet the requirements for a canonical Text_IO 21415file has one of the following: 21416 21417 21418@itemize * 21419 21420@item 21421The file contains @code{FF} characters not immediately following a 21422@code{LF} character. 21423 21424@item 21425The file contains @code{LF} or @code{FF} characters written by 21426@code{Put} or @code{Put_Line}, which are not logically considered to be 21427line marks or page marks. 21428 21429@item 21430The file ends in a character other than @code{LF} or @code{FF}, 21431i.e., there is no explicit line mark or page mark at the end of the file. 21432@end itemize 21433 21434Text_IO can be used to read such non-standard text files but subprograms 21435to do with line or page numbers do not have defined meanings. In 21436particular, a @code{FF} character that does not follow a @code{LF} 21437character may or may not be treated as a page mark from the point of 21438view of page and line numbering. Every @code{LF} character is considered 21439to end a line, and there is an implied @code{LF} character at the end of 21440the file. 21441 21442@menu 21443* Stream Pointer Positioning:: 21444* Reading and Writing Non-Regular Files:: 21445* Get_Immediate:: 21446* Treating Text_IO Files as Streams:: 21447* Text_IO Extensions:: 21448* Text_IO Facilities for Unbounded Strings:: 21449 21450@end menu 21451 21452@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21453@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2a3} 21454@subsection Stream Pointer Positioning 21455 21456 21457@code{Ada.Text_IO} has a definition of current position for a file that 21458is being read. No internal buffering occurs in Text_IO, and usually the 21459physical position in the stream used to implement the file corresponds 21460to this logical position defined by Text_IO. There are two exceptions: 21461 21462 21463@itemize * 21464 21465@item 21466After a call to @code{End_Of_Page} that returns @code{True}, the stream 21467is positioned past the @code{LF} (line mark) that precedes the page 21468mark. Text_IO maintains an internal flag so that subsequent read 21469operations properly handle the logical position which is unchanged by 21470the @code{End_Of_Page} call. 21471 21472@item 21473After a call to @code{End_Of_File} that returns @code{True}, if the 21474Text_IO file was positioned before the line mark at the end of file 21475before the call, then the logical position is unchanged, but the stream 21476is physically positioned right at the end of file (past the line mark, 21477and past a possible page mark following the line mark. Again Text_IO 21478maintains internal flags so that subsequent read operations properly 21479handle the logical position. 21480@end itemize 21481 21482These discrepancies have no effect on the observable behavior of 21483Text_IO, but if a single Ada stream is shared between a C program and 21484Ada program, or shared (using @code{shared=yes} in the form string) 21485between two Ada files, then the difference may be observable in some 21486situations. 21487 21488@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21489@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2a4}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2a5} 21490@subsection Reading and Writing Non-Regular Files 21491 21492 21493A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21494can be used for reading and writing. Writing is not affected and the 21495sequence of characters output is identical to the normal file case, but 21496for reading, the behavior of Text_IO is modified to avoid undesirable 21497look-ahead as follows: 21498 21499An input file that is not a regular file is considered to have no page 21500marks. Any @code{Ascii.FF} characters (the character normally used for a 21501page mark) appearing in the file are considered to be data 21502characters. In particular: 21503 21504 21505@itemize * 21506 21507@item 21508@code{Get_Line} and @code{Skip_Line} do not test for a page mark 21509following a line mark. If a page mark appears, it will be treated as a 21510data character. 21511 21512@item 21513This avoids the need to wait for an extra character to be typed or 21514entered from the pipe to complete one of these operations. 21515 21516@item 21517@code{End_Of_Page} always returns @code{False} 21518 21519@item 21520@code{End_Of_File} will return @code{False} if there is a page mark at 21521the end of the file. 21522@end itemize 21523 21524Output to non-regular files is the same as for regular files. Page marks 21525may be written to non-regular files using @code{New_Page}, but as noted 21526above they will not be treated as page marks on input if the output is 21527piped to another Ada program. 21528 21529Another important discrepancy when reading non-regular files is that the end 21530of file indication is not 'sticky'. If an end of file is entered, e.g., by 21531pressing the @code{EOT} key, 21532then end of file 21533is signaled once (i.e., the test @code{End_Of_File} 21534will yield @code{True}, or a read will 21535raise @code{End_Error}), but then reading can resume 21536to read data past that end of 21537file indication, until another end of file indication is entered. 21538 21539@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21540@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2a6}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2a7} 21541@subsection Get_Immediate 21542 21543 21544@geindex Get_Immediate 21545 21546Get_Immediate returns the next character (including control characters) 21547from the input file. In particular, Get_Immediate will return LF or FF 21548characters used as line marks or page marks. Such operations leave the 21549file positioned past the control character, and it is thus not treated 21550as having its normal function. This means that page, line and column 21551counts after this kind of Get_Immediate call are set as though the mark 21552did not occur. In the case where a Get_Immediate leaves the file 21553positioned between the line mark and page mark (which is not normally 21554possible), it is undefined whether the FF character will be treated as a 21555page mark. 21556 21557@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21558@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2a8}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2a9} 21559@subsection Treating Text_IO Files as Streams 21560 21561 21562@geindex Stream files 21563 21564The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated 21565as a stream. Data written to a @code{Text_IO} file in this stream mode is 21566binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 2156716#0C# (@code{FF}), the resulting file may have non-standard 21568format. Similarly if read operations are used to read from a Text_IO 21569file treated as a stream, then @code{LF} and @code{FF} characters may be 21570skipped and the effect is similar to that described above for 21571@code{Get_Immediate}. 21572 21573@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 21574@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2aa}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2ab} 21575@subsection Text_IO Extensions 21576 21577 21578@geindex Text_IO extensions 21579 21580A package GNAT.IO_Aux in the GNAT library provides some useful extensions 21581to the standard @code{Text_IO} package: 21582 21583 21584@itemize * 21585 21586@item 21587function File_Exists (Name : String) return Boolean; 21588Determines if a file of the given name exists. 21589 21590@item 21591function Get_Line return String; 21592Reads a string from the standard input file. The value returned is exactly 21593the length of the line that was read. 21594 21595@item 21596function Get_Line (File : Ada.Text_IO.File_Type) return String; 21597Similar, except that the parameter File specifies the file from which 21598the string is to be read. 21599@end itemize 21600 21601@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 21602@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2ac}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2ad} 21603@subsection Text_IO Facilities for Unbounded Strings 21604 21605 21606@geindex Text_IO for unbounded strings 21607 21608@geindex Unbounded_String 21609@geindex Text_IO operations 21610 21611The package @code{Ada.Strings.Unbounded.Text_IO} 21612in library files @code{a-suteio.ads/adb} contains some GNAT-specific 21613subprograms useful for Text_IO operations on unbounded strings: 21614 21615 21616@itemize * 21617 21618@item 21619function Get_Line (File : File_Type) return Unbounded_String; 21620Reads a line from the specified file 21621and returns the result as an unbounded string. 21622 21623@item 21624procedure Put (File : File_Type; U : Unbounded_String); 21625Writes the value of the given unbounded string to the specified file 21626Similar to the effect of 21627@code{Put (To_String (U))} except that an extra copy is avoided. 21628 21629@item 21630procedure Put_Line (File : File_Type; U : Unbounded_String); 21631Writes the value of the given unbounded string to the specified file, 21632followed by a @code{New_Line}. 21633Similar to the effect of @code{Put_Line (To_String (U))} except 21634that an extra copy is avoided. 21635@end itemize 21636 21637In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 21638and is optional. If the parameter is omitted, then the standard input or 21639output file is referenced as appropriate. 21640 21641The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 21642files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 21643@code{Wide_Text_IO} functionality for unbounded wide strings. 21644 21645The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 21646files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 21647@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 21648 21649@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 21650@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2af} 21651@section Wide_Text_IO 21652 21653 21654@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 21655both input and output files may contain special sequences that represent 21656wide character values. The encoding scheme for a given file may be 21657specified using a FORM parameter: 21658 21659@example 21660WCEM=`x` 21661@end example 21662 21663as part of the FORM string (WCEM = wide character encoding method), 21664where @code{x} is one of the following characters 21665 21666 21667@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21668@headitem 21669 21670Character 21671 21672@tab 21673 21674Encoding 21675 21676@item 21677 21678@emph{h} 21679 21680@tab 21681 21682Hex ESC encoding 21683 21684@item 21685 21686@emph{u} 21687 21688@tab 21689 21690Upper half encoding 21691 21692@item 21693 21694@emph{s} 21695 21696@tab 21697 21698Shift-JIS encoding 21699 21700@item 21701 21702@emph{e} 21703 21704@tab 21705 21706EUC Encoding 21707 21708@item 21709 21710@emph{8} 21711 21712@tab 21713 21714UTF-8 encoding 21715 21716@item 21717 21718@emph{b} 21719 21720@tab 21721 21722Brackets encoding 21723 21724@end multitable 21725 21726 21727The encoding methods match those that 21728can be used in a source 21729program, but there is no requirement that the encoding method used for 21730the source program be the same as the encoding method used for files, 21731and different files may use different encoding methods. 21732 21733The default encoding method for the standard files, and for opened files 21734for which no WCEM parameter is given in the FORM string matches the 21735wide character encoding specified for the main program (the default 21736being brackets encoding if no coding method was specified with -gnatW). 21737 21738 21739@table @asis 21740 21741@item @emph{Hex Coding} 21742 21743In this encoding, a wide character is represented by a five character 21744sequence: 21745@end table 21746 21747@example 21748ESC a b c d 21749@end example 21750 21751 21752@quotation 21753 21754where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 21755characters (using upper case letters) of the wide character code. For 21756example, ESC A345 is used to represent the wide character with code 2175716#A345#. This scheme is compatible with use of the full 21758@code{Wide_Character} set. 21759@end quotation 21760 21761 21762@table @asis 21763 21764@item @emph{Upper Half Coding} 21765 21766The wide character with encoding 16#abcd#, where the upper bit is on 21767(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2176816#cd#. The second byte may never be a format control character, but is 21769not required to be in the upper half. This method can be also used for 21770shift-JIS or EUC where the internal coding matches the external coding. 21771 21772@item @emph{Shift JIS Coding} 21773 21774A wide character is represented by a two character sequence 16#ab# and 2177516#cd#, with the restrictions described for upper half encoding as 21776described above. The internal character code is the corresponding JIS 21777character according to the standard algorithm for Shift-JIS 21778conversion. Only characters defined in the JIS code set table can be 21779used with this encoding method. 21780 21781@item @emph{EUC Coding} 21782 21783A wide character is represented by a two character sequence 16#ab# and 2178416#cd#, with both characters being in the upper half. The internal 21785character code is the corresponding JIS character according to the EUC 21786encoding algorithm. Only characters defined in the JIS code set table 21787can be used with this encoding method. 21788 21789@item @emph{UTF-8 Coding} 21790 21791A wide character is represented using 21792UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2179310646-1/Am.2. Depending on the character value, the representation 21794is a one, two, or three byte sequence: 21795@end table 21796 21797@example 2179816#0000#-16#007f#: 2#0xxxxxxx# 2179916#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2180016#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 21801@end example 21802 21803 21804@quotation 21805 21806where the @code{xxx} bits correspond to the left-padded bits of the 2180716-bit character value. Note that all lower half ASCII characters 21808are represented as ASCII bytes and all upper half characters and 21809other wide characters are represented as sequences of upper-half 21810(The full UTF-8 scheme allows for encoding 31-bit characters as 218116-byte sequences, but in this implementation, all UTF-8 sequences 21812of four or more bytes length will raise a Constraint_Error, as 21813will all invalid UTF-8 sequences.) 21814@end quotation 21815 21816 21817@table @asis 21818 21819@item @emph{Brackets Coding} 21820 21821In this encoding, a wide character is represented by the following eight 21822character sequence: 21823@end table 21824 21825@example 21826[ " a b c d " ] 21827@end example 21828 21829 21830@quotation 21831 21832where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 21833characters (using uppercase letters) of the wide character code. For 21834example, @code{["A345"]} is used to represent the wide character with code 21835@code{16#A345#}. 21836This scheme is compatible with use of the full Wide_Character set. 21837On input, brackets coding can also be used for upper half characters, 21838e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 21839is only used for wide characters with a code greater than @code{16#FF#}. 21840 21841Note that brackets coding is not normally used in the context of 21842Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 21843a portable way of encoding source files. In the context of Wide_Text_IO 21844or Wide_Wide_Text_IO, it can only be used if the file does not contain 21845any instance of the left bracket character other than to encode wide 21846character values using the brackets encoding method. In practice it is 21847expected that some standard wide character encoding method such 21848as UTF-8 will be used for text input output. 21849 21850If brackets notation is used, then any occurrence of a left bracket 21851in the input file which is not the start of a valid wide character 21852sequence will cause Constraint_Error to be raised. It is possible to 21853encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 21854input will interpret this as a left bracket. 21855 21856However, when a left bracket is output, it will be output as a left bracket 21857and not as ["5B"]. We make this decision because for normal use of 21858Wide_Text_IO for outputting messages, it is unpleasant to clobber left 21859brackets. For example, if we write: 21860 21861@example 21862Put_Line ("Start of output [first run]"); 21863@end example 21864 21865we really do not want to have the left bracket in this message clobbered so 21866that the output reads: 21867@end quotation 21868 21869@example 21870Start of output ["5B"]first run] 21871@end example 21872 21873 21874@quotation 21875 21876In practice brackets encoding is reasonably useful for normal Put_Line use 21877since we won't get confused between left brackets and wide character 21878sequences in the output. But for input, or when files are written out 21879and read back in, it really makes better sense to use one of the standard 21880encoding methods such as UTF-8. 21881@end quotation 21882 21883For the coding schemes other than UTF-8, Hex, or Brackets encoding, 21884not all wide character 21885values can be represented. An attempt to output a character that cannot 21886be represented using the encoding scheme for the file causes 21887Constraint_Error to be raised. An invalid wide character sequence on 21888input also causes Constraint_Error to be raised. 21889 21890@menu 21891* Stream Pointer Positioning: Stream Pointer Positioning<2>. 21892* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 21893 21894@end menu 21895 21896@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 21897@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2b0}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2b1} 21898@subsection Stream Pointer Positioning 21899 21900 21901@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 21902of stream pointer positioning (@ref{2a1,,Text_IO}). There is one additional 21903case: 21904 21905If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 21906normal lower ASCII set (i.e., a character in the range: 21907 21908@example 21909Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 21910@end example 21911 21912then although the logical position of the file pointer is unchanged by 21913the @code{Look_Ahead} call, the stream is physically positioned past the 21914wide character sequence. Again this is to avoid the need for buffering 21915or backup, and all @code{Wide_Text_IO} routines check the internal 21916indication that this situation has occurred so that this is not visible 21917to a normal program using @code{Wide_Text_IO}. However, this discrepancy 21918can be observed if the wide text file shares a stream with another file. 21919 21920@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 21921@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2b2}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2b3} 21922@subsection Reading and Writing Non-Regular Files 21923 21924 21925As in the case of Text_IO, when a non-regular file is read, it is 21926assumed that the file contains no page marks (any form characters are 21927treated as data characters), and @code{End_Of_Page} always returns 21928@code{False}. Similarly, the end of file indication is not sticky, so 21929it is possible to read beyond an end of file. 21930 21931@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 21932@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2b4}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2b5} 21933@section Wide_Wide_Text_IO 21934 21935 21936@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 21937both input and output files may contain special sequences that represent 21938wide wide character values. The encoding scheme for a given file may be 21939specified using a FORM parameter: 21940 21941@example 21942WCEM=`x` 21943@end example 21944 21945as part of the FORM string (WCEM = wide character encoding method), 21946where @code{x} is one of the following characters 21947 21948 21949@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21950@headitem 21951 21952Character 21953 21954@tab 21955 21956Encoding 21957 21958@item 21959 21960@emph{h} 21961 21962@tab 21963 21964Hex ESC encoding 21965 21966@item 21967 21968@emph{u} 21969 21970@tab 21971 21972Upper half encoding 21973 21974@item 21975 21976@emph{s} 21977 21978@tab 21979 21980Shift-JIS encoding 21981 21982@item 21983 21984@emph{e} 21985 21986@tab 21987 21988EUC Encoding 21989 21990@item 21991 21992@emph{8} 21993 21994@tab 21995 21996UTF-8 encoding 21997 21998@item 21999 22000@emph{b} 22001 22002@tab 22003 22004Brackets encoding 22005 22006@end multitable 22007 22008 22009The encoding methods match those that 22010can be used in a source 22011program, but there is no requirement that the encoding method used for 22012the source program be the same as the encoding method used for files, 22013and different files may use different encoding methods. 22014 22015The default encoding method for the standard files, and for opened files 22016for which no WCEM parameter is given in the FORM string matches the 22017wide character encoding specified for the main program (the default 22018being brackets encoding if no coding method was specified with -gnatW). 22019 22020 22021@table @asis 22022 22023@item @emph{UTF-8 Coding} 22024 22025A wide character is represented using 22026UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2202710646-1/Am.2. Depending on the character value, the representation 22028is a one, two, three, or four byte sequence: 22029@end table 22030 22031@example 2203216#000000#-16#00007f#: 2#0xxxxxxx# 2203316#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2203416#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2203516#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 22036@end example 22037 22038 22039@quotation 22040 22041where the @code{xxx} bits correspond to the left-padded bits of the 2204221-bit character value. Note that all lower half ASCII characters 22043are represented as ASCII bytes and all upper half characters and 22044other wide characters are represented as sequences of upper-half 22045characters. 22046@end quotation 22047 22048 22049@table @asis 22050 22051@item @emph{Brackets Coding} 22052 22053In this encoding, a wide wide character is represented by the following eight 22054character sequence if is in wide character range 22055@end table 22056 22057@example 22058[ " a b c d " ] 22059@end example 22060 22061 22062@quotation 22063 22064and by the following ten character sequence if not 22065@end quotation 22066 22067@example 22068[ " a b c d e f " ] 22069@end example 22070 22071 22072@quotation 22073 22074where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 22075are the four or six hexadecimal 22076characters (using uppercase letters) of the wide wide character code. For 22077example, @code{["01A345"]} is used to represent the wide wide character 22078with code @code{16#01A345#}. 22079 22080This scheme is compatible with use of the full Wide_Wide_Character set. 22081On input, brackets coding can also be used for upper half characters, 22082e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22083is only used for wide characters with a code greater than @code{16#FF#}. 22084@end quotation 22085 22086If is also possible to use the other Wide_Character encoding methods, 22087such as Shift-JIS, but the other schemes cannot support the full range 22088of wide wide characters. 22089An attempt to output a character that cannot 22090be represented using the encoding scheme for the file causes 22091Constraint_Error to be raised. An invalid wide character sequence on 22092input also causes Constraint_Error to be raised. 22093 22094@menu 22095* Stream Pointer Positioning: Stream Pointer Positioning<3>. 22096* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 22097 22098@end menu 22099 22100@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 22101@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2b6}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2b7} 22102@subsection Stream Pointer Positioning 22103 22104 22105@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22106of stream pointer positioning (@ref{2a1,,Text_IO}). There is one additional 22107case: 22108 22109If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 22110normal lower ASCII set (i.e., a character in the range: 22111 22112@example 22113Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 22114@end example 22115 22116then although the logical position of the file pointer is unchanged by 22117the @code{Look_Ahead} call, the stream is physically positioned past the 22118wide character sequence. Again this is to avoid the need for buffering 22119or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 22120indication that this situation has occurred so that this is not visible 22121to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 22122can be observed if the wide text file shares a stream with another file. 22123 22124@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 22125@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2b8}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2b9} 22126@subsection Reading and Writing Non-Regular Files 22127 22128 22129As in the case of Text_IO, when a non-regular file is read, it is 22130assumed that the file contains no page marks (any form characters are 22131treated as data characters), and @code{End_Of_Page} always returns 22132@code{False}. Similarly, the end of file indication is not sticky, so 22133it is possible to read beyond an end of file. 22134 22135@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 22136@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2ba}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2bb} 22137@section Stream_IO 22138 22139 22140A stream file is a sequence of bytes, where individual elements are 22141written to the file as described in the Ada Reference Manual. The type 22142@code{Stream_Element} is simply a byte. There are two ways to read or 22143write a stream file. 22144 22145 22146@itemize * 22147 22148@item 22149The operations @code{Read} and @code{Write} directly read or write a 22150sequence of stream elements with no control information. 22151 22152@item 22153The stream attributes applied to a stream file transfer data in the 22154manner described for stream attributes. 22155@end itemize 22156 22157@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 22158@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2bc}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2bd} 22159@section Text Translation 22160 22161 22162@code{Text_Translation=xxx} may be used as the Form parameter 22163passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 22164has no effect on Unix systems. Possible values are: 22165 22166 22167@itemize * 22168 22169@item 22170@code{Yes} or @code{Text} is the default, which means to 22171translate LF to/from CR/LF on Windows systems. 22172 22173@code{No} disables this translation; i.e. it 22174uses binary mode. For output files, @code{Text_Translation=No} 22175may be used to create Unix-style files on 22176Windows. 22177 22178@item 22179@code{wtext} translation enabled in Unicode mode. 22180(corresponds to _O_WTEXT). 22181 22182@item 22183@code{u8text} translation enabled in Unicode UTF-8 mode. 22184(corresponds to O_U8TEXT). 22185 22186@item 22187@code{u16text} translation enabled in Unicode UTF-16 22188mode. (corresponds to_O_U16TEXT). 22189@end itemize 22190 22191@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 22192@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2be}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2bf} 22193@section Shared Files 22194 22195 22196Section A.14 of the Ada Reference Manual allows implementations to 22197provide a wide variety of behavior if an attempt is made to access the 22198same external file with two or more internal files. 22199 22200To provide a full range of functionality, while at the same time 22201minimizing the problems of portability caused by this implementation 22202dependence, GNAT handles file sharing as follows: 22203 22204 22205@itemize * 22206 22207@item 22208In the absence of a @code{shared=xxx} form parameter, an attempt 22209to open two or more files with the same full name is considered an error 22210and is not supported. The exception @code{Use_Error} will be 22211raised. Note that a file that is not explicitly closed by the program 22212remains open until the program terminates. 22213 22214@item 22215If the form parameter @code{shared=no} appears in the form string, the 22216file can be opened or created with its own separate stream identifier, 22217regardless of whether other files sharing the same external file are 22218opened. The exact effect depends on how the C stream routines handle 22219multiple accesses to the same external files using separate streams. 22220 22221@item 22222If the form parameter @code{shared=yes} appears in the form string for 22223each of two or more files opened using the same full name, the same 22224stream is shared between these files, and the semantics are as described 22225in Ada Reference Manual, Section A.14. 22226@end itemize 22227 22228When a program that opens multiple files with the same name is ported 22229from another Ada compiler to GNAT, the effect will be that 22230@code{Use_Error} is raised. 22231 22232The documentation of the original compiler and the documentation of the 22233program should then be examined to determine if file sharing was 22234expected, and @code{shared=xxx} parameters added to @code{Open} 22235and @code{Create} calls as required. 22236 22237When a program is ported from GNAT to some other Ada compiler, no 22238special attention is required unless the @code{shared=xxx} form 22239parameter is used in the program. In this case, you must examine the 22240documentation of the new compiler to see if it supports the required 22241file sharing semantics, and form strings modified appropriately. Of 22242course it may be the case that the program cannot be ported if the 22243target compiler does not support the required functionality. The best 22244approach in writing portable code is to avoid file sharing (and hence 22245the use of the @code{shared=xxx} parameter in the form string) 22246completely. 22247 22248One common use of file sharing in Ada 83 is the use of instantiations of 22249Sequential_IO on the same file with different types, to achieve 22250heterogeneous input-output. Although this approach will work in GNAT if 22251@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 22252for this purpose (using the stream attributes) 22253 22254@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 22255@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2c0}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2c1} 22256@section Filenames encoding 22257 22258 22259An encoding form parameter can be used to specify the filename 22260encoding @code{encoding=xxx}. 22261 22262 22263@itemize * 22264 22265@item 22266If the form parameter @code{encoding=utf8} appears in the form string, the 22267filename must be encoded in UTF-8. 22268 22269@item 22270If the form parameter @code{encoding=8bits} appears in the form 22271string, the filename must be a standard 8bits string. 22272@end itemize 22273 22274In the absence of a @code{encoding=xxx} form parameter, the 22275encoding is controlled by the @code{GNAT_CODE_PAGE} environment 22276variable. And if not set @code{utf8} is assumed. 22277 22278 22279@table @asis 22280 22281@item @emph{CP_ACP} 22282 22283The current system Windows ANSI code page. 22284 22285@item @emph{CP_UTF8} 22286 22287UTF-8 encoding 22288@end table 22289 22290This encoding form parameter is only supported on the Windows 22291platform. On the other Operating Systems the run-time is supporting 22292UTF-8 natively. 22293 22294@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 22295@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2c2}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2c3} 22296@section File content encoding 22297 22298 22299For text files it is possible to specify the encoding to use. This is 22300controlled by the by the @code{GNAT_CCS_ENCODING} environment 22301variable. And if not set @code{TEXT} is assumed. 22302 22303The possible values are those supported on Windows: 22304 22305 22306@table @asis 22307 22308@item @emph{TEXT} 22309 22310Translated text mode 22311 22312@item @emph{WTEXT} 22313 22314Translated unicode encoding 22315 22316@item @emph{U16TEXT} 22317 22318Unicode 16-bit encoding 22319 22320@item @emph{U8TEXT} 22321 22322Unicode 8-bit encoding 22323@end table 22324 22325This encoding is only supported on the Windows platform. 22326 22327@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 22328@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2c4}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2c5} 22329@section Open Modes 22330 22331 22332@code{Open} and @code{Create} calls result in a call to @code{fopen} 22333using the mode shown in the following table: 22334 22335 22336@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 22337@headitem 22338 22339@code{Open} and @code{Create} Call Modes 22340 22341@tab 22342 22343@tab 22344 22345@item 22346 22347@tab 22348 22349@strong{OPEN} 22350 22351@tab 22352 22353@strong{CREATE} 22354 22355@item 22356 22357Append_File 22358 22359@tab 22360 22361"r+" 22362 22363@tab 22364 22365"w+" 22366 22367@item 22368 22369In_File 22370 22371@tab 22372 22373"r" 22374 22375@tab 22376 22377"w+" 22378 22379@item 22380 22381Out_File (Direct_IO) 22382 22383@tab 22384 22385"r+" 22386 22387@tab 22388 22389"w" 22390 22391@item 22392 22393Out_File (all other cases) 22394 22395@tab 22396 22397"w" 22398 22399@tab 22400 22401"w" 22402 22403@item 22404 22405Inout_File 22406 22407@tab 22408 22409"r+" 22410 22411@tab 22412 22413"w+" 22414 22415@end multitable 22416 22417 22418If text file translation is required, then either @code{b} or @code{t} 22419is added to the mode, depending on the setting of Text. Text file 22420translation refers to the mapping of CR/LF sequences in an external file 22421to LF characters internally. This mapping only occurs in DOS and 22422DOS-like systems, and is not relevant to other systems. 22423 22424A special case occurs with Stream_IO. As shown in the above table, the 22425file is initially opened in @code{r} or @code{w} mode for the 22426@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 22427subsequently requires switching from reading to writing or vice-versa, 22428then the file is reopened in @code{r+} mode to permit the required operation. 22429 22430@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22431@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2c6}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2c7} 22432@section Operations on C Streams 22433 22434 22435The package @code{Interfaces.C_Streams} provides an Ada program with direct 22436access to the C library functions for operations on C streams: 22437 22438@example 22439package Interfaces.C_Streams is 22440 -- Note: the reason we do not use the types that are in 22441 -- Interfaces.C is that we want to avoid dragging in the 22442 -- code in this unit if possible. 22443 subtype chars is System.Address; 22444 -- Pointer to null-terminated array of characters 22445 subtype FILEs is System.Address; 22446 -- Corresponds to the C type FILE* 22447 subtype voids is System.Address; 22448 -- Corresponds to the C type void* 22449 subtype int is Integer; 22450 subtype long is Long_Integer; 22451 -- Note: the above types are subtypes deliberately, and it 22452 -- is part of this spec that the above correspondences are 22453 -- guaranteed. This means that it is legitimate to, for 22454 -- example, use Integer instead of int. We provide these 22455 -- synonyms for clarity, but in some cases it may be 22456 -- convenient to use the underlying types (for example to 22457 -- avoid an unnecessary dependency of a spec on the spec 22458 -- of this unit). 22459 type size_t is mod 2 ** Standard'Address_Size; 22460 NULL_Stream : constant FILEs; 22461 -- Value returned (NULL in C) to indicate an 22462 -- fdopen/fopen/tmpfile error 22463 ---------------------------------- 22464 -- Constants Defined in stdio.h -- 22465 ---------------------------------- 22466 EOF : constant int; 22467 -- Used by a number of routines to indicate error or 22468 -- end of file 22469 IOFBF : constant int; 22470 IOLBF : constant int; 22471 IONBF : constant int; 22472 -- Used to indicate buffering mode for setvbuf call 22473 SEEK_CUR : constant int; 22474 SEEK_END : constant int; 22475 SEEK_SET : constant int; 22476 -- Used to indicate origin for fseek call 22477 function stdin return FILEs; 22478 function stdout return FILEs; 22479 function stderr return FILEs; 22480 -- Streams associated with standard files 22481 -------------------------- 22482 -- Standard C functions -- 22483 -------------------------- 22484 -- The functions selected below are ones that are 22485 -- available in UNIX (but not necessarily in ANSI C). 22486 -- These are very thin interfaces 22487 -- which copy exactly the C headers. For more 22488 -- documentation on these functions, see the Microsoft C 22489 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22490 -- ISBN 1-55615-225-6), which includes useful information 22491 -- on system compatibility. 22492 procedure clearerr (stream : FILEs); 22493 function fclose (stream : FILEs) return int; 22494 function fdopen (handle : int; mode : chars) return FILEs; 22495 function feof (stream : FILEs) return int; 22496 function ferror (stream : FILEs) return int; 22497 function fflush (stream : FILEs) return int; 22498 function fgetc (stream : FILEs) return int; 22499 function fgets (strng : chars; n : int; stream : FILEs) 22500 return chars; 22501 function fileno (stream : FILEs) return int; 22502 function fopen (filename : chars; Mode : chars) 22503 return FILEs; 22504 -- Note: to maintain target independence, use 22505 -- text_translation_required, a boolean variable defined in 22506 -- a-sysdep.c to deal with the target dependent text 22507 -- translation requirement. If this variable is set, 22508 -- then b/t should be appended to the standard mode 22509 -- argument to set the text translation mode off or on 22510 -- as required. 22511 function fputc (C : int; stream : FILEs) return int; 22512 function fputs (Strng : chars; Stream : FILEs) return int; 22513 function fread 22514 (buffer : voids; 22515 size : size_t; 22516 count : size_t; 22517 stream : FILEs) 22518 return size_t; 22519 function freopen 22520 (filename : chars; 22521 mode : chars; 22522 stream : FILEs) 22523 return FILEs; 22524 function fseek 22525 (stream : FILEs; 22526 offset : long; 22527 origin : int) 22528 return int; 22529 function ftell (stream : FILEs) return long; 22530 function fwrite 22531 (buffer : voids; 22532 size : size_t; 22533 count : size_t; 22534 stream : FILEs) 22535 return size_t; 22536 function isatty (handle : int) return int; 22537 procedure mktemp (template : chars); 22538 -- The return value (which is just a pointer to template) 22539 -- is discarded 22540 procedure rewind (stream : FILEs); 22541 function rmtmp return int; 22542 function setvbuf 22543 (stream : FILEs; 22544 buffer : chars; 22545 mode : int; 22546 size : size_t) 22547 return int; 22548 22549 function tmpfile return FILEs; 22550 function ungetc (c : int; stream : FILEs) return int; 22551 function unlink (filename : chars) return int; 22552 --------------------- 22553 -- Extra functions -- 22554 --------------------- 22555 -- These functions supply slightly thicker bindings than 22556 -- those above. They are derived from functions in the 22557 -- C Run-Time Library, but may do a bit more work than 22558 -- just directly calling one of the Library functions. 22559 function is_regular_file (handle : int) return int; 22560 -- Tests if given handle is for a regular file (result 1) 22561 -- or for a non-regular file (pipe or device, result 0). 22562 --------------------------------- 22563 -- Control of Text/Binary Mode -- 22564 --------------------------------- 22565 -- If text_translation_required is true, then the following 22566 -- functions may be used to dynamically switch a file from 22567 -- binary to text mode or vice versa. These functions have 22568 -- no effect if text_translation_required is false (i.e., in 22569 -- normal UNIX mode). Use fileno to get a stream handle. 22570 procedure set_binary_mode (handle : int); 22571 procedure set_text_mode (handle : int); 22572 ---------------------------- 22573 -- Full Path Name support -- 22574 ---------------------------- 22575 procedure full_name (nam : chars; buffer : chars); 22576 -- Given a NUL terminated string representing a file 22577 -- name, returns in buffer a NUL terminated string 22578 -- representing the full path name for the file name. 22579 -- On systems where it is relevant the drive is also 22580 -- part of the full path name. It is the responsibility 22581 -- of the caller to pass an actual parameter for buffer 22582 -- that is big enough for any full path name. Use 22583 -- max_path_len given below as the size of buffer. 22584 max_path_len : integer; 22585 -- Maximum length of an allowable full path name on the 22586 -- system, including a terminating NUL character. 22587end Interfaces.C_Streams; 22588@end example 22589 22590@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 22591@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2c8}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2c9} 22592@section Interfacing to C Streams 22593 22594 22595The packages in this section permit interfacing Ada files to C Stream 22596operations. 22597 22598@example 22599with Interfaces.C_Streams; 22600package Ada.Sequential_IO.C_Streams is 22601 function C_Stream (F : File_Type) 22602 return Interfaces.C_Streams.FILEs; 22603 procedure Open 22604 (File : in out File_Type; 22605 Mode : in File_Mode; 22606 C_Stream : in Interfaces.C_Streams.FILEs; 22607 Form : in String := ""); 22608end Ada.Sequential_IO.C_Streams; 22609 22610 with Interfaces.C_Streams; 22611 package Ada.Direct_IO.C_Streams is 22612 function C_Stream (F : File_Type) 22613 return Interfaces.C_Streams.FILEs; 22614 procedure Open 22615 (File : in out File_Type; 22616 Mode : in File_Mode; 22617 C_Stream : in Interfaces.C_Streams.FILEs; 22618 Form : in String := ""); 22619 end Ada.Direct_IO.C_Streams; 22620 22621 with Interfaces.C_Streams; 22622 package Ada.Text_IO.C_Streams is 22623 function C_Stream (F : File_Type) 22624 return Interfaces.C_Streams.FILEs; 22625 procedure Open 22626 (File : in out File_Type; 22627 Mode : in File_Mode; 22628 C_Stream : in Interfaces.C_Streams.FILEs; 22629 Form : in String := ""); 22630 end Ada.Text_IO.C_Streams; 22631 22632 with Interfaces.C_Streams; 22633 package Ada.Wide_Text_IO.C_Streams is 22634 function C_Stream (F : File_Type) 22635 return Interfaces.C_Streams.FILEs; 22636 procedure Open 22637 (File : in out File_Type; 22638 Mode : in File_Mode; 22639 C_Stream : in Interfaces.C_Streams.FILEs; 22640 Form : in String := ""); 22641end Ada.Wide_Text_IO.C_Streams; 22642 22643 with Interfaces.C_Streams; 22644 package Ada.Wide_Wide_Text_IO.C_Streams is 22645 function C_Stream (F : File_Type) 22646 return Interfaces.C_Streams.FILEs; 22647 procedure Open 22648 (File : in out File_Type; 22649 Mode : in File_Mode; 22650 C_Stream : in Interfaces.C_Streams.FILEs; 22651 Form : in String := ""); 22652end Ada.Wide_Wide_Text_IO.C_Streams; 22653 22654with Interfaces.C_Streams; 22655package Ada.Stream_IO.C_Streams is 22656 function C_Stream (F : File_Type) 22657 return Interfaces.C_Streams.FILEs; 22658 procedure Open 22659 (File : in out File_Type; 22660 Mode : in File_Mode; 22661 C_Stream : in Interfaces.C_Streams.FILEs; 22662 Form : in String := ""); 22663end Ada.Stream_IO.C_Streams; 22664@end example 22665 22666In each of these six packages, the @code{C_Stream} function obtains the 22667@code{FILE} pointer from a currently opened Ada file. It is then 22668possible to use the @code{Interfaces.C_Streams} package to operate on 22669this stream, or the stream can be passed to a C program which can 22670operate on it directly. Of course the program is responsible for 22671ensuring that only appropriate sequences of operations are executed. 22672 22673One particular use of relevance to an Ada program is that the 22674@code{setvbuf} function can be used to control the buffering of the 22675stream used by an Ada file. In the absence of such a call the standard 22676default buffering is used. 22677 22678The @code{Open} procedures in these packages open a file giving an 22679existing C Stream instead of a file name. Typically this stream is 22680imported from a C program, allowing an Ada file to operate on an 22681existing C file. 22682 22683@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 22684@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2ca}@anchor{gnat_rm/the_gnat_library id1}@anchor{2cb} 22685@chapter The GNAT Library 22686 22687 22688The GNAT library contains a number of general and special purpose packages. 22689It represents functionality that the GNAT developers have found useful, and 22690which is made available to GNAT users. The packages described here are fully 22691supported, and upwards compatibility will be maintained in future releases, 22692so you can use these facilities with the confidence that the same functionality 22693will be available in future releases. 22694 22695The chapter here simply gives a brief summary of the facilities available. 22696The full documentation is found in the spec file for the package. The full 22697sources of these library packages, including both spec and body, are provided 22698with all GNAT releases. For example, to find out the full specifications of 22699the SPITBOL pattern matching capability, including a full tutorial and 22700extensive examples, look in the @code{g-spipat.ads} file in the library. 22701 22702For each entry here, the package name (as it would appear in a @code{with} 22703clause) is given, followed by the name of the corresponding spec file in 22704parentheses. The packages are children in four hierarchies, @code{Ada}, 22705@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 22706GNAT-specific hierarchy. 22707 22708Note that an application program should only use packages in one of these 22709four hierarchies if the package is defined in the Ada Reference Manual, 22710or is listed in this section of the GNAT Programmers Reference Manual. 22711All other units should be considered internal implementation units and 22712should not be directly @code{with}ed by application code. The use of 22713a @code{with} clause that references one of these internal implementation 22714units makes an application potentially dependent on changes in versions 22715of GNAT, and will generate a warning message. 22716 22717@menu 22718* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 22719* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 22720* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 22721* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 22722* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 22723* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 22724* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 22725* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 22726* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 22727* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 22728* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 22729* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 22730* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 22731* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 22732* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 22733* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 22734* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 22735* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 22736* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 22737* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 22738* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 22739* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 22740* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 22741* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 22742* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 22743* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 22744* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 22745* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 22746* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 22747* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 22748* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 22749* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 22750* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 22751* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 22752* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 22753* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 22754* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 22755* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 22756* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 22757* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 22758* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 22759* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 22760* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 22761* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 22762* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 22763* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 22764* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 22765* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 22766* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 22767* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 22768* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 22769* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 22770* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 22771* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 22772* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 22773* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 22774* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 22775* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 22776* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 22777* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 22778* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 22779* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 22780* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 22781* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 22782* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 22783* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 22784* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 22785* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 22786* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 22787* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 22788* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 22789* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 22790* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 22791* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 22792* GNAT.Exceptions (g-expect.ads): GNAT Exceptions g-expect ads. 22793* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 22794* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 22795* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 22796* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 22797* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 22798* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 22799* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 22800* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 22801* GNAT.IO (g-io.ads): GNAT IO g-io ads. 22802* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 22803* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 22804* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 22805* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 22806* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 22807* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 22808* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 22809* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 22810* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 22811* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 22812* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 22813* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 22814* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 22815* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 22816* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 22817* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 22818* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 22819* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 22820* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 22821* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 22822* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 22823* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 22824* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 22825* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 22826* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 22827* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 22828* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 22829* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 22830* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 22831* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 22832* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 22833* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 22834* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 22835* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 22836* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 22837* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 22838* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 22839* GNAT.Table (g-table.ads): GNAT Table g-table ads. 22840* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 22841* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 22842* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 22843* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 22844* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 22845* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 22846* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 22847* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 22848* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 22849* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 22850* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 22851* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 22852* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 22853* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 22854* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 22855* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 22856* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 22857* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 22858* System.Assertions (s-assert.ads): System Assertions s-assert ads. 22859* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 22860* System.Memory (s-memory.ads): System Memory s-memory ads. 22861* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 22862* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 22863* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 22864* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 22865* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 22866* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 22867* System.Rident (s-rident.ads): System Rident s-rident ads. 22868* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 22869* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 22870* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 22871* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 22872 22873@end menu 22874 22875@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 22876@anchor{gnat_rm/the_gnat_library id2}@anchor{2cc}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2cd} 22877@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 22878 22879 22880@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 22881 22882@geindex Latin_9 constants for Character 22883 22884This child of @code{Ada.Characters} 22885provides a set of definitions corresponding to those in the 22886RM-defined package @code{Ada.Characters.Latin_1} but with the 22887few modifications required for @code{Latin-9} 22888The provision of such a package 22889is specifically authorized by the Ada Reference Manual 22890(RM A.3.3(27)). 22891 22892@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 22893@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2ce}@anchor{gnat_rm/the_gnat_library id3}@anchor{2cf} 22894@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 22895 22896 22897@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 22898 22899@geindex Latin_1 constants for Wide_Character 22900 22901This child of @code{Ada.Characters} 22902provides a set of definitions corresponding to those in the 22903RM-defined package @code{Ada.Characters.Latin_1} but with the 22904types of the constants being @code{Wide_Character} 22905instead of @code{Character}. The provision of such a package 22906is specifically authorized by the Ada Reference Manual 22907(RM A.3.3(27)). 22908 22909@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 22910@anchor{gnat_rm/the_gnat_library id4}@anchor{2d0}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2d1} 22911@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 22912 22913 22914@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 22915 22916@geindex Latin_9 constants for Wide_Character 22917 22918This child of @code{Ada.Characters} 22919provides a set of definitions corresponding to those in the 22920GNAT defined package @code{Ada.Characters.Latin_9} but with the 22921types of the constants being @code{Wide_Character} 22922instead of @code{Character}. The provision of such a package 22923is specifically authorized by the Ada Reference Manual 22924(RM A.3.3(27)). 22925 22926@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 22927@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2d2}@anchor{gnat_rm/the_gnat_library id5}@anchor{2d3} 22928@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 22929 22930 22931@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 22932 22933@geindex Latin_1 constants for Wide_Wide_Character 22934 22935This child of @code{Ada.Characters} 22936provides a set of definitions corresponding to those in the 22937RM-defined package @code{Ada.Characters.Latin_1} but with the 22938types of the constants being @code{Wide_Wide_Character} 22939instead of @code{Character}. The provision of such a package 22940is specifically authorized by the Ada Reference Manual 22941(RM A.3.3(27)). 22942 22943@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 22944@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2d4}@anchor{gnat_rm/the_gnat_library id6}@anchor{2d5} 22945@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 22946 22947 22948@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 22949 22950@geindex Latin_9 constants for Wide_Wide_Character 22951 22952This child of @code{Ada.Characters} 22953provides a set of definitions corresponding to those in the 22954GNAT defined package @code{Ada.Characters.Latin_9} but with the 22955types of the constants being @code{Wide_Wide_Character} 22956instead of @code{Character}. The provision of such a package 22957is specifically authorized by the Ada Reference Manual 22958(RM A.3.3(27)). 22959 22960@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 22961@anchor{gnat_rm/the_gnat_library id7}@anchor{2d6}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2d7} 22962@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 22963 22964 22965@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 22966 22967@geindex Formal container for doubly linked lists 22968 22969This child of @code{Ada.Containers} defines a modified version of the 22970Ada 2005 container for doubly linked lists, meant to facilitate formal 22971verification of code using such containers. The specification of this 22972unit is compatible with SPARK 2014. 22973 22974Note that although this container was designed with formal verification 22975in mind, it may well be generally useful in that it is a simplified more 22976efficient version than the one defined in the standard. In particular it 22977does not have the complex overhead required to detect cursor tampering. 22978 22979@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 22980@anchor{gnat_rm/the_gnat_library id8}@anchor{2d8}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2d9} 22981@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 22982 22983 22984@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 22985 22986@geindex Formal container for hashed maps 22987 22988This child of @code{Ada.Containers} defines a modified version of the 22989Ada 2005 container for hashed maps, meant to facilitate formal 22990verification of code using such containers. The specification of this 22991unit is compatible with SPARK 2014. 22992 22993Note that although this container was designed with formal verification 22994in mind, it may well be generally useful in that it is a simplified more 22995efficient version than the one defined in the standard. In particular it 22996does not have the complex overhead required to detect cursor tampering. 22997 22998@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 22999@anchor{gnat_rm/the_gnat_library id9}@anchor{2da}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2db} 23000@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 23001 23002 23003@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 23004 23005@geindex Formal container for hashed sets 23006 23007This child of @code{Ada.Containers} defines a modified version of the 23008Ada 2005 container for hashed sets, meant to facilitate formal 23009verification of code using such containers. The specification of this 23010unit is compatible with SPARK 2014. 23011 23012Note that although this container was designed with formal verification 23013in mind, it may well be generally useful in that it is a simplified more 23014efficient version than the one defined in the standard. In particular it 23015does not have the complex overhead required to detect cursor tampering. 23016 23017@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 23018@anchor{gnat_rm/the_gnat_library id10}@anchor{2dc}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2dd} 23019@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 23020 23021 23022@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 23023 23024@geindex Formal container for ordered maps 23025 23026This child of @code{Ada.Containers} defines a modified version of the 23027Ada 2005 container for ordered maps, meant to facilitate formal 23028verification of code using such containers. The specification of this 23029unit is compatible with SPARK 2014. 23030 23031Note that although this container was designed with formal verification 23032in mind, it may well be generally useful in that it is a simplified more 23033efficient version than the one defined in the standard. In particular it 23034does not have the complex overhead required to detect cursor tampering. 23035 23036@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 23037@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2de}@anchor{gnat_rm/the_gnat_library id11}@anchor{2df} 23038@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 23039 23040 23041@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 23042 23043@geindex Formal container for ordered sets 23044 23045This child of @code{Ada.Containers} defines a modified version of the 23046Ada 2005 container for ordered sets, meant to facilitate formal 23047verification of code using such containers. The specification of this 23048unit is compatible with SPARK 2014. 23049 23050Note that although this container was designed with formal verification 23051in mind, it may well be generally useful in that it is a simplified more 23052efficient version than the one defined in the standard. In particular it 23053does not have the complex overhead required to detect cursor tampering. 23054 23055@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 23056@anchor{gnat_rm/the_gnat_library id12}@anchor{2e0}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2e1} 23057@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 23058 23059 23060@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 23061 23062@geindex Formal container for vectors 23063 23064This child of @code{Ada.Containers} defines a modified version of the 23065Ada 2005 container for vectors, meant to facilitate formal 23066verification of code using such containers. The specification of this 23067unit is compatible with SPARK 2014. 23068 23069Note that although this container was designed with formal verification 23070in mind, it may well be generally useful in that it is a simplified more 23071efficient version than the one defined in the standard. In particular it 23072does not have the complex overhead required to detect cursor tampering. 23073 23074@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 23075@anchor{gnat_rm/the_gnat_library id13}@anchor{2e2}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2e3} 23076@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 23077 23078 23079@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 23080 23081@geindex Formal container for vectors 23082 23083This child of @code{Ada.Containers} defines a modified version of the 23084Ada 2005 container for vectors of indefinite elements, meant to 23085facilitate formal verification of code using such containers. The 23086specification of this unit is compatible with SPARK 2014. 23087 23088Note that although this container was designed with formal verification 23089in mind, it may well be generally useful in that it is a simplified more 23090efficient version than the one defined in the standard. In particular it 23091does not have the complex overhead required to detect cursor tampering. 23092 23093@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 23094@anchor{gnat_rm/the_gnat_library id14}@anchor{2e4}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2e5} 23095@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) 23096 23097 23098@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) 23099 23100@geindex Functional vectors 23101 23102This child of @code{Ada.Containers} defines immutable vectors. These 23103containers are unbounded and may contain indefinite elements. Furthermore, to 23104be usable in every context, they are neither controlled nor limited. As they 23105are functional, that is, no primitives are provided which would allow modifying 23106an existing container, these containers can still be used safely. 23107 23108Their API features functions creating new containers from existing ones. 23109As a consequence, these containers are highly inefficient. They are also 23110memory consuming, as the allocated memory is not reclaimed when the container 23111is no longer referenced. Thus, they should in general be used in ghost code 23112and annotations, so that they can be removed from the final executable. The 23113specification of this unit is compatible with SPARK 2014. 23114 23115@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 23116@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2e6}@anchor{gnat_rm/the_gnat_library id15}@anchor{2e7} 23117@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) 23118 23119 23120@geindex Ada.Containers.Functional_Sets (a-cofuse.ads) 23121 23122@geindex Functional sets 23123 23124This child of @code{Ada.Containers} defines immutable sets. These containers are 23125unbounded and may contain indefinite elements. Furthermore, to be usable in 23126every context, they are neither controlled nor limited. As they are functional, 23127that is, no primitives are provided which would allow modifying an existing 23128container, these containers can still be used safely. 23129 23130Their API features functions creating new containers from existing ones. 23131As a consequence, these containers are highly inefficient. They are also 23132memory consuming, as the allocated memory is not reclaimed when the container 23133is no longer referenced. Thus, they should in general be used in ghost code 23134and annotations, so that they can be removed from the final executable. The 23135specification of this unit is compatible with SPARK 2014. 23136 23137@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 23138@anchor{gnat_rm/the_gnat_library id16}@anchor{2e8}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2e9} 23139@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) 23140 23141 23142@geindex Ada.Containers.Functional_Maps (a-cofuma.ads) 23143 23144@geindex Functional maps 23145 23146This child of @code{Ada.Containers} defines immutable maps. These containers are 23147unbounded and may contain indefinite elements. Furthermore, to be usable in 23148every context, they are neither controlled nor limited. As they are functional, 23149that is, no primitives are provided which would allow modifying an existing 23150container, these containers can still be used safely. 23151 23152Their API features functions creating new containers from existing ones. 23153As a consequence, these containers are highly inefficient. They are also 23154memory consuming, as the allocated memory is not reclaimed when the container 23155is no longer referenced. Thus, they should in general be used in ghost code 23156and annotations, so that they can be removed from the final executable. The 23157specification of this unit is compatible with SPARK 2014. 23158 23159@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 23160@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2ea}@anchor{gnat_rm/the_gnat_library id17}@anchor{2eb} 23161@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 23162 23163 23164@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 23165 23166@geindex Formal container for vectors 23167 23168This child of @code{Ada.Containers} defines a modified version of 23169Indefinite_Holders that avoids heap allocation. 23170 23171@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 23172@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2ec}@anchor{gnat_rm/the_gnat_library id18}@anchor{2ed} 23173@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) 23174 23175 23176@geindex Ada.Command_Line.Environment (a-colien.ads) 23177 23178@geindex Environment entries 23179 23180This child of @code{Ada.Command_Line} 23181provides a mechanism for obtaining environment values on systems 23182where this concept makes sense. 23183 23184@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 23185@anchor{gnat_rm/the_gnat_library id19}@anchor{2ee}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2ef} 23186@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) 23187 23188 23189@geindex Ada.Command_Line.Remove (a-colire.ads) 23190 23191@geindex Removing command line arguments 23192 23193@geindex Command line 23194@geindex argument removal 23195 23196This child of @code{Ada.Command_Line} 23197provides a mechanism for logically removing 23198arguments from the argument list. Once removed, an argument is not visible 23199to further calls on the subprograms in @code{Ada.Command_Line} will not 23200see the removed argument. 23201 23202@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 23203@anchor{gnat_rm/the_gnat_library id20}@anchor{2f0}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2f1} 23204@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 23205 23206 23207@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 23208 23209@geindex Response file for command line 23210 23211@geindex Command line 23212@geindex response file 23213 23214@geindex Command line 23215@geindex handling long command lines 23216 23217This child of @code{Ada.Command_Line} provides a mechanism facilities for 23218getting command line arguments from a text file, called a "response file". 23219Using a response file allow passing a set of arguments to an executable longer 23220than the maximum allowed by the system on the command line. 23221 23222@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 23223@anchor{gnat_rm/the_gnat_library id21}@anchor{2f2}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2f3} 23224@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 23225 23226 23227@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 23228 23229@geindex C Streams 23230@geindex Interfacing with Direct_IO 23231 23232This package provides subprograms that allow interfacing between 23233C streams and @code{Direct_IO}. The stream identifier can be 23234extracted from a file opened on the Ada side, and an Ada file 23235can be constructed from a stream opened on the C side. 23236 23237@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 23238@anchor{gnat_rm/the_gnat_library id22}@anchor{2f4}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f5} 23239@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 23240 23241 23242@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 23243 23244@geindex Null_Occurrence 23245@geindex testing for 23246 23247This child subprogram provides a way of testing for the null 23248exception occurrence (@code{Null_Occurrence}) without raising 23249an exception. 23250 23251@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 23252@anchor{gnat_rm/the_gnat_library id23}@anchor{2f6}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2f7} 23253@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 23254 23255 23256@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 23257 23258@geindex Null_Occurrence 23259@geindex testing for 23260 23261This child subprogram is used for handling otherwise unhandled 23262exceptions (hence the name last chance), and perform clean ups before 23263terminating the program. Note that this subprogram never returns. 23264 23265@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 23266@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2f8}@anchor{gnat_rm/the_gnat_library id24}@anchor{2f9} 23267@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 23268 23269 23270@geindex Ada.Exceptions.Traceback (a-exctra.ads) 23271 23272@geindex Traceback for Exception Occurrence 23273 23274This child package provides the subprogram (@code{Tracebacks}) to 23275give a traceback array of addresses based on an exception 23276occurrence. 23277 23278@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 23279@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2fa}@anchor{gnat_rm/the_gnat_library id25}@anchor{2fb} 23280@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 23281 23282 23283@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 23284 23285@geindex C Streams 23286@geindex Interfacing with Sequential_IO 23287 23288This package provides subprograms that allow interfacing between 23289C streams and @code{Sequential_IO}. The stream identifier can be 23290extracted from a file opened on the Ada side, and an Ada file 23291can be constructed from a stream opened on the C side. 23292 23293@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 23294@anchor{gnat_rm/the_gnat_library id26}@anchor{2fc}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2fd} 23295@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 23296 23297 23298@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 23299 23300@geindex C Streams 23301@geindex Interfacing with Stream_IO 23302 23303This package provides subprograms that allow interfacing between 23304C streams and @code{Stream_IO}. The stream identifier can be 23305extracted from a file opened on the Ada side, and an Ada file 23306can be constructed from a stream opened on the C side. 23307 23308@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 23309@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2fe}@anchor{gnat_rm/the_gnat_library id27}@anchor{2ff} 23310@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 23311 23312 23313@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 23314 23315@geindex Unbounded_String 23316@geindex IO support 23317 23318@geindex Text_IO 23319@geindex extensions for unbounded strings 23320 23321This package provides subprograms for Text_IO for unbounded 23322strings, avoiding the necessity for an intermediate operation 23323with ordinary strings. 23324 23325@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 23326@anchor{gnat_rm/the_gnat_library id28}@anchor{300}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{301} 23327@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 23328 23329 23330@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 23331 23332@geindex Unbounded_Wide_String 23333@geindex IO support 23334 23335@geindex Text_IO 23336@geindex extensions for unbounded wide strings 23337 23338This package provides subprograms for Text_IO for unbounded 23339wide strings, avoiding the necessity for an intermediate operation 23340with ordinary wide strings. 23341 23342@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 23343@anchor{gnat_rm/the_gnat_library id29}@anchor{302}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{303} 23344@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 23345 23346 23347@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 23348 23349@geindex Unbounded_Wide_Wide_String 23350@geindex IO support 23351 23352@geindex Text_IO 23353@geindex extensions for unbounded wide wide strings 23354 23355This package provides subprograms for Text_IO for unbounded 23356wide wide strings, avoiding the necessity for an intermediate operation 23357with ordinary wide wide strings. 23358 23359@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 23360@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{304}@anchor{gnat_rm/the_gnat_library id30}@anchor{305} 23361@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 23362 23363 23364@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 23365 23366@geindex C Streams 23367@geindex Interfacing with `@w{`}Text_IO`@w{`} 23368 23369This package provides subprograms that allow interfacing between 23370C streams and @code{Text_IO}. The stream identifier can be 23371extracted from a file opened on the Ada side, and an Ada file 23372can be constructed from a stream opened on the C side. 23373 23374@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 23375@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{306}@anchor{gnat_rm/the_gnat_library id31}@anchor{307} 23376@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 23377 23378 23379@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 23380 23381@geindex Text_IO resetting standard files 23382 23383This procedure is used to reset the status of the standard files used 23384by Ada.Text_IO. This is useful in a situation (such as a restart in an 23385embedded application) where the status of the files may change during 23386execution (for example a standard input file may be redefined to be 23387interactive). 23388 23389@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 23390@anchor{gnat_rm/the_gnat_library id32}@anchor{308}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{309} 23391@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 23392 23393 23394@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 23395 23396@geindex Unicode categorization 23397@geindex Wide_Character 23398 23399This package provides subprograms that allow categorization of 23400Wide_Character values according to Unicode categories. 23401 23402@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 23403@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{30a}@anchor{gnat_rm/the_gnat_library id33}@anchor{30b} 23404@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 23405 23406 23407@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 23408 23409@geindex C Streams 23410@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} 23411 23412This package provides subprograms that allow interfacing between 23413C streams and @code{Wide_Text_IO}. The stream identifier can be 23414extracted from a file opened on the Ada side, and an Ada file 23415can be constructed from a stream opened on the C side. 23416 23417@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 23418@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{30c}@anchor{gnat_rm/the_gnat_library id34}@anchor{30d} 23419@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 23420 23421 23422@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 23423 23424@geindex Wide_Text_IO resetting standard files 23425 23426This procedure is used to reset the status of the standard files used 23427by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 23428embedded application) where the status of the files may change during 23429execution (for example a standard input file may be redefined to be 23430interactive). 23431 23432@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 23433@anchor{gnat_rm/the_gnat_library id35}@anchor{30e}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{30f} 23434@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 23435 23436 23437@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 23438 23439@geindex Unicode categorization 23440@geindex Wide_Wide_Character 23441 23442This package provides subprograms that allow categorization of 23443Wide_Wide_Character values according to Unicode categories. 23444 23445@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 23446@anchor{gnat_rm/the_gnat_library id36}@anchor{310}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{311} 23447@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 23448 23449 23450@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 23451 23452@geindex C Streams 23453@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} 23454 23455This package provides subprograms that allow interfacing between 23456C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 23457extracted from a file opened on the Ada side, and an Ada file 23458can be constructed from a stream opened on the C side. 23459 23460@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 23461@anchor{gnat_rm/the_gnat_library id37}@anchor{312}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{313} 23462@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 23463 23464 23465@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 23466 23467@geindex Wide_Wide_Text_IO resetting standard files 23468 23469This procedure is used to reset the status of the standard files used 23470by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 23471restart in an embedded application) where the status of the files may 23472change during execution (for example a standard input file may be 23473redefined to be interactive). 23474 23475@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 23476@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{314}@anchor{gnat_rm/the_gnat_library id38}@anchor{315} 23477@section @code{GNAT.Altivec} (@code{g-altive.ads}) 23478 23479 23480@geindex GNAT.Altivec (g-altive.ads) 23481 23482@geindex AltiVec 23483 23484This is the root package of the GNAT AltiVec binding. It provides 23485definitions of constants and types common to all the versions of the 23486binding. 23487 23488@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 23489@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{316}@anchor{gnat_rm/the_gnat_library id39}@anchor{317} 23490@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 23491 23492 23493@geindex GNAT.Altivec.Conversions (g-altcon.ads) 23494 23495@geindex AltiVec 23496 23497This package provides the Vector/View conversion routines. 23498 23499@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23500@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{318}@anchor{gnat_rm/the_gnat_library id40}@anchor{319} 23501@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23502 23503 23504@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23505 23506@geindex AltiVec 23507 23508This package exposes the Ada interface to the AltiVec operations on 23509vector objects. A soft emulation is included by default in the GNAT 23510library. The hard binding is provided as a separate package. This unit 23511is common to both bindings. 23512 23513@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 23514@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{31a}@anchor{gnat_rm/the_gnat_library id41}@anchor{31b} 23515@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23516 23517 23518@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23519 23520@geindex AltiVec 23521 23522This package exposes the various vector types part of the Ada binding 23523to AltiVec facilities. 23524 23525@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23526@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{31c}@anchor{gnat_rm/the_gnat_library id42}@anchor{31d} 23527@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23528 23529 23530@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23531 23532@geindex AltiVec 23533 23534This package provides public 'View' data types from/to which private 23535vector representations can be converted via 23536GNAT.Altivec.Conversions. This allows convenient access to individual 23537vector elements and provides a simple way to initialize vector 23538objects. 23539 23540@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23541@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{31e}@anchor{gnat_rm/the_gnat_library id43}@anchor{31f} 23542@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) 23543 23544 23545@geindex GNAT.Array_Split (g-arrspl.ads) 23546 23547@geindex Array splitter 23548 23549Useful array-manipulation routines: given a set of separators, split 23550an array wherever the separators appear, and provide direct access 23551to the resulting slices. 23552 23553@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 23554@anchor{gnat_rm/the_gnat_library id44}@anchor{320}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{321} 23555@section @code{GNAT.AWK} (@code{g-awk.ads}) 23556 23557 23558@geindex GNAT.AWK (g-awk.ads) 23559 23560@geindex Parsing 23561 23562@geindex AWK 23563 23564Provides AWK-like parsing functions, with an easy interface for parsing one 23565or more files containing formatted data. The file is viewed as a database 23566where each record is a line and a field is a data element in this line. 23567 23568@node GNAT Bind_Environment g-binenv ads,GNAT Bounded_Buffers g-boubuf ads,GNAT AWK g-awk ads,The GNAT Library 23569@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{322}@anchor{gnat_rm/the_gnat_library id45}@anchor{323} 23570@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) 23571 23572 23573@geindex GNAT.Bind_Environment (g-binenv.ads) 23574 23575@geindex Bind environment 23576 23577Provides access to key=value associations captured at bind time. 23578These associations can be specified using the @code{-V} binder command 23579line switch. 23580 23581@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 23582@anchor{gnat_rm/the_gnat_library id46}@anchor{324}@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{325} 23583@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 23584 23585 23586@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 23587 23588@geindex Parsing 23589 23590@geindex Bounded Buffers 23591 23592Provides a concurrent generic bounded buffer abstraction. Instances are 23593useful directly or as parts of the implementations of other abstractions, 23594such as mailboxes. 23595 23596@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 23597@anchor{gnat_rm/the_gnat_library id47}@anchor{326}@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{327} 23598@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 23599 23600 23601@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 23602 23603@geindex Parsing 23604 23605@geindex Mailboxes 23606 23607Provides a thread-safe asynchronous intertask mailbox communication facility. 23608 23609@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 23610@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{328}@anchor{gnat_rm/the_gnat_library id48}@anchor{329} 23611@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 23612 23613 23614@geindex GNAT.Bubble_Sort (g-bubsor.ads) 23615 23616@geindex Sorting 23617 23618@geindex Bubble sort 23619 23620Provides a general implementation of bubble sort usable for sorting arbitrary 23621data items. Exchange and comparison procedures are provided by passing 23622access-to-procedure values. 23623 23624@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 23625@anchor{gnat_rm/the_gnat_library id49}@anchor{32a}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{32b} 23626@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 23627 23628 23629@geindex GNAT.Bubble_Sort_A (g-busora.ads) 23630 23631@geindex Sorting 23632 23633@geindex Bubble sort 23634 23635Provides a general implementation of bubble sort usable for sorting arbitrary 23636data items. Move and comparison procedures are provided by passing 23637access-to-procedure values. This is an older version, retained for 23638compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 23639 23640@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 23641@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{32c}@anchor{gnat_rm/the_gnat_library id50}@anchor{32d} 23642@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 23643 23644 23645@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 23646 23647@geindex Sorting 23648 23649@geindex Bubble sort 23650 23651Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 23652are provided as generic parameters, this improves efficiency, especially 23653if the procedures can be inlined, at the expense of duplicating code for 23654multiple instantiations. 23655 23656@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 23657@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{32e}@anchor{gnat_rm/the_gnat_library id51}@anchor{32f} 23658@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 23659 23660 23661@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 23662 23663@geindex UTF-8 representation 23664 23665@geindex Wide characte representations 23666 23667Provides a routine which given a string, reads the start of the string to 23668see whether it is one of the standard byte order marks (BOM's) which signal 23669the encoding of the string. The routine includes detection of special XML 23670sequences for various UCS input formats. 23671 23672@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 23673@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{330}@anchor{gnat_rm/the_gnat_library id52}@anchor{331} 23674@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 23675 23676 23677@geindex GNAT.Byte_Swapping (g-bytswa.ads) 23678 23679@geindex Byte swapping 23680 23681@geindex Endianness 23682 23683General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 23684Machine-specific implementations are available in some cases. 23685 23686@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 23687@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{332}@anchor{gnat_rm/the_gnat_library id53}@anchor{333} 23688@section @code{GNAT.Calendar} (@code{g-calend.ads}) 23689 23690 23691@geindex GNAT.Calendar (g-calend.ads) 23692 23693@geindex Calendar 23694 23695Extends the facilities provided by @code{Ada.Calendar} to include handling 23696of days of the week, an extended @code{Split} and @code{Time_Of} capability. 23697Also provides conversion of @code{Ada.Calendar.Time} values to and from the 23698C @code{timeval} format. 23699 23700@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 23701@anchor{gnat_rm/the_gnat_library id54}@anchor{334}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{335} 23702@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 23703 23704 23705@geindex Calendar 23706 23707@geindex Time 23708 23709@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 23710 23711@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 23712@anchor{gnat_rm/the_gnat_library id55}@anchor{336}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{337} 23713@section @code{GNAT.CRC32} (@code{g-crc32.ads}) 23714 23715 23716@geindex GNAT.CRC32 (g-crc32.ads) 23717 23718@geindex CRC32 23719 23720@geindex Cyclic Redundancy Check 23721 23722This package implements the CRC-32 algorithm. For a full description 23723of this algorithm see 23724@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 23725@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 23726Aug. 1988. Sarwate, D.V. 23727 23728@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 23729@anchor{gnat_rm/the_gnat_library id56}@anchor{338}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{339} 23730@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) 23731 23732 23733@geindex GNAT.Case_Util (g-casuti.ads) 23734 23735@geindex Casing utilities 23736 23737@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) 23738 23739A set of simple routines for handling upper and lower casing of strings 23740without the overhead of the full casing tables 23741in @code{Ada.Characters.Handling}. 23742 23743@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 23744@anchor{gnat_rm/the_gnat_library id57}@anchor{33a}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{33b} 23745@section @code{GNAT.CGI} (@code{g-cgi.ads}) 23746 23747 23748@geindex GNAT.CGI (g-cgi.ads) 23749 23750@geindex CGI (Common Gateway Interface) 23751 23752This is a package for interfacing a GNAT program with a Web server via the 23753Common Gateway Interface (CGI). Basically this package parses the CGI 23754parameters, which are a set of key/value pairs sent by the Web server. It 23755builds a table whose index is the key and provides some services to deal 23756with this table. 23757 23758@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 23759@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{33c}@anchor{gnat_rm/the_gnat_library id58}@anchor{33d} 23760@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 23761 23762 23763@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 23764 23765@geindex CGI (Common Gateway Interface) cookie support 23766 23767@geindex Cookie support in CGI 23768 23769This is a package to interface a GNAT program with a Web server via the 23770Common Gateway Interface (CGI). It exports services to deal with Web 23771cookies (piece of information kept in the Web client software). 23772 23773@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 23774@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{33e}@anchor{gnat_rm/the_gnat_library id59}@anchor{33f} 23775@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 23776 23777 23778@geindex GNAT.CGI.Debug (g-cgideb.ads) 23779 23780@geindex CGI (Common Gateway Interface) debugging 23781 23782This is a package to help debugging CGI (Common Gateway Interface) 23783programs written in Ada. 23784 23785@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 23786@anchor{gnat_rm/the_gnat_library id60}@anchor{340}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{341} 23787@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) 23788 23789 23790@geindex GNAT.Command_Line (g-comlin.ads) 23791 23792@geindex Command line 23793 23794Provides a high level interface to @code{Ada.Command_Line} facilities, 23795including the ability to scan for named switches with optional parameters 23796and expand file names using wild card notations. 23797 23798@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 23799@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{342}@anchor{gnat_rm/the_gnat_library id61}@anchor{343} 23800@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) 23801 23802 23803@geindex GNAT.Compiler_Version (g-comver.ads) 23804 23805@geindex Compiler Version 23806 23807@geindex Version 23808@geindex of compiler 23809 23810Provides a routine for obtaining the version of the compiler used to 23811compile the program. More accurately this is the version of the binder 23812used to bind the program (this will normally be the same as the version 23813of the compiler if a consistent tool set is used to compile all units 23814of a partition). 23815 23816@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 23817@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{344}@anchor{gnat_rm/the_gnat_library id62}@anchor{345} 23818@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 23819 23820 23821@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 23822 23823@geindex Interrupt 23824 23825Provides a simple interface to handle Ctrl-C keyboard events. 23826 23827@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 23828@anchor{gnat_rm/the_gnat_library id63}@anchor{346}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{347} 23829@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) 23830 23831 23832@geindex GNAT.Current_Exception (g-curexc.ads) 23833 23834@geindex Current exception 23835 23836@geindex Exception retrieval 23837 23838Provides access to information on the current exception that has been raised 23839without the need for using the Ada 95 / Ada 2005 exception choice parameter 23840specification syntax. 23841This is particularly useful in simulating typical facilities for 23842obtaining information about exceptions provided by Ada 83 compilers. 23843 23844@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 23845@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{348}@anchor{gnat_rm/the_gnat_library id64}@anchor{349} 23846@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 23847 23848 23849@geindex GNAT.Debug_Pools (g-debpoo.ads) 23850 23851@geindex Debugging 23852 23853@geindex Debug pools 23854 23855@geindex Memory corruption debugging 23856 23857Provide a debugging storage pools that helps tracking memory corruption 23858problems. 23859See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}. 23860 23861@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 23862@anchor{gnat_rm/the_gnat_library id65}@anchor{34a}@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{34b} 23863@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 23864 23865 23866@geindex GNAT.Debug_Utilities (g-debuti.ads) 23867 23868@geindex Debugging 23869 23870Provides a few useful utilities for debugging purposes, including conversion 23871to and from string images of address values. Supports both C and Ada formats 23872for hexadecimal literals. 23873 23874@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 23875@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id66}@anchor{34d} 23876@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) 23877 23878 23879@geindex GNAT.Decode_String (g-decstr.ads) 23880 23881@geindex Decoding strings 23882 23883@geindex String decoding 23884 23885@geindex Wide character encoding 23886 23887@geindex UTF-8 23888 23889@geindex Unicode 23890 23891A generic package providing routines for decoding wide character and wide wide 23892character strings encoded as sequences of 8-bit characters using a specified 23893encoding method. Includes validation routines, and also routines for stepping 23894to next or previous encoded character in an encoded string. 23895Useful in conjunction with Unicode character coding. Note there is a 23896preinstantiation for UTF-8. See next entry. 23897 23898@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 23899@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{34e}@anchor{gnat_rm/the_gnat_library id67}@anchor{34f} 23900@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 23901 23902 23903@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 23904 23905@geindex Decoding strings 23906 23907@geindex Decoding UTF-8 strings 23908 23909@geindex UTF-8 string decoding 23910 23911@geindex Wide character decoding 23912 23913@geindex UTF-8 23914 23915@geindex Unicode 23916 23917A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 23918 23919@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 23920@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{350}@anchor{gnat_rm/the_gnat_library id68}@anchor{351} 23921@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) 23922 23923 23924@geindex GNAT.Directory_Operations (g-dirope.ads) 23925 23926@geindex Directory operations 23927 23928Provides a set of routines for manipulating directories, including changing 23929the current directory, making new directories, and scanning the files in a 23930directory. 23931 23932@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 23933@anchor{gnat_rm/the_gnat_library id69}@anchor{352}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{353} 23934@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 23935 23936 23937@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 23938 23939@geindex Directory operations iteration 23940 23941A child unit of GNAT.Directory_Operations providing additional operations 23942for iterating through directories. 23943 23944@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 23945@anchor{gnat_rm/the_gnat_library id70}@anchor{354}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{355} 23946@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 23947 23948 23949@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 23950 23951@geindex Hash tables 23952 23953A generic implementation of hash tables that can be used to hash arbitrary 23954data. Provided in two forms, a simple form with built in hash functions, 23955and a more complex form in which the hash function is supplied. 23956 23957This package provides a facility similar to that of @code{GNAT.HTable}, 23958except that this package declares a type that can be used to define 23959dynamic instances of the hash table, while an instantiation of 23960@code{GNAT.HTable} creates a single instance of the hash table. 23961 23962@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 23963@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{356}@anchor{gnat_rm/the_gnat_library id71}@anchor{357} 23964@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 23965 23966 23967@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 23968 23969@geindex Table implementation 23970 23971@geindex Arrays 23972@geindex extendable 23973 23974A generic package providing a single dimension array abstraction where the 23975length of the array can be dynamically modified. 23976 23977This package provides a facility similar to that of @code{GNAT.Table}, 23978except that this package declares a type that can be used to define 23979dynamic instances of the table, while an instantiation of 23980@code{GNAT.Table} creates a single instance of the table type. 23981 23982@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 23983@anchor{gnat_rm/the_gnat_library id72}@anchor{358}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{359} 23984@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) 23985 23986 23987@geindex GNAT.Encode_String (g-encstr.ads) 23988 23989@geindex Encoding strings 23990 23991@geindex String encoding 23992 23993@geindex Wide character encoding 23994 23995@geindex UTF-8 23996 23997@geindex Unicode 23998 23999A generic package providing routines for encoding wide character and wide 24000wide character strings as sequences of 8-bit characters using a specified 24001encoding method. Useful in conjunction with Unicode character coding. 24002Note there is a preinstantiation for UTF-8. See next entry. 24003 24004@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 24005@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{35a}@anchor{gnat_rm/the_gnat_library id73}@anchor{35b} 24006@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 24007 24008 24009@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 24010 24011@geindex Encoding strings 24012 24013@geindex Encoding UTF-8 strings 24014 24015@geindex UTF-8 string encoding 24016 24017@geindex Wide character encoding 24018 24019@geindex UTF-8 24020 24021@geindex Unicode 24022 24023A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 24024 24025@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 24026@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{35c}@anchor{gnat_rm/the_gnat_library id74}@anchor{35d} 24027@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) 24028 24029 24030@geindex GNAT.Exception_Actions (g-excact.ads) 24031 24032@geindex Exception actions 24033 24034Provides callbacks when an exception is raised. Callbacks can be registered 24035for specific exceptions, or when any exception is raised. This 24036can be used for instance to force a core dump to ease debugging. 24037 24038@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-expect ads,GNAT Exception_Actions g-excact ads,The GNAT Library 24039@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{35e}@anchor{gnat_rm/the_gnat_library id75}@anchor{35f} 24040@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) 24041 24042 24043@geindex GNAT.Exception_Traces (g-exctra.ads) 24044 24045@geindex Exception traces 24046 24047@geindex Debugging 24048 24049Provides an interface allowing to control automatic output upon exception 24050occurrences. 24051 24052@node GNAT Exceptions g-expect ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 24053@anchor{gnat_rm/the_gnat_library id76}@anchor{360}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-expect-ads}@anchor{361} 24054@section @code{GNAT.Exceptions} (@code{g-expect.ads}) 24055 24056 24057@geindex GNAT.Exceptions (g-expect.ads) 24058 24059@geindex Exceptions 24060@geindex Pure 24061 24062@geindex Pure packages 24063@geindex exceptions 24064 24065Normally it is not possible to raise an exception with 24066a message from a subprogram in a pure package, since the 24067necessary types and subprograms are in @code{Ada.Exceptions} 24068which is not a pure unit. @code{GNAT.Exceptions} provides a 24069facility for getting around this limitation for a few 24070predefined exceptions, and for example allow raising 24071@code{Constraint_Error} with a message from a pure subprogram. 24072 24073@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-expect ads,The GNAT Library 24074@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{362}@anchor{gnat_rm/the_gnat_library id77}@anchor{363} 24075@section @code{GNAT.Expect} (@code{g-expect.ads}) 24076 24077 24078@geindex GNAT.Expect (g-expect.ads) 24079 24080Provides a set of subprograms similar to what is available 24081with the standard Tcl Expect tool. 24082It allows you to easily spawn and communicate with an external process. 24083You can send commands or inputs to the process, and compare the output 24084with some expected regular expression. Currently @code{GNAT.Expect} 24085is implemented on all native GNAT ports. 24086It is not implemented for cross ports, and in particular is not 24087implemented for VxWorks or LynxOS. 24088 24089@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 24090@anchor{gnat_rm/the_gnat_library id78}@anchor{364}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{365} 24091@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) 24092 24093 24094@geindex GNAT.Expect.TTY (g-exptty.ads) 24095 24096As GNAT.Expect but using pseudo-terminal. 24097Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 24098ports. It is not implemented for cross ports, and 24099in particular is not implemented for VxWorks or LynxOS. 24100 24101@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 24102@anchor{gnat_rm/the_gnat_library id79}@anchor{366}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{367} 24103@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) 24104 24105 24106@geindex GNAT.Float_Control (g-flocon.ads) 24107 24108@geindex Floating-Point Processor 24109 24110Provides an interface for resetting the floating-point processor into the 24111mode required for correct semantic operation in Ada. Some third party 24112library calls may cause this mode to be modified, and the Reset procedure 24113in this package can be used to reestablish the required mode. 24114 24115@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 24116@anchor{gnat_rm/the_gnat_library id80}@anchor{368}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{369} 24117@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) 24118 24119 24120@geindex GNAT.Formatted_String (g-forstr.ads) 24121 24122@geindex Formatted String 24123 24124Provides support for C/C++ printf() formatted strings. The format is 24125copied from the printf() routine and should therefore gives identical 24126output. Some generic routines are provided to be able to use types 24127derived from Integer, Float or enumerations as values for the 24128formatted string. 24129 24130@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 24131@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{36a}@anchor{gnat_rm/the_gnat_library id81}@anchor{36b} 24132@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) 24133 24134 24135@geindex GNAT.Heap_Sort (g-heasor.ads) 24136 24137@geindex Sorting 24138 24139Provides a general implementation of heap sort usable for sorting arbitrary 24140data items. Exchange and comparison procedures are provided by passing 24141access-to-procedure values. The algorithm used is a modified heap sort 24142that performs approximately N*log(N) comparisons in the worst case. 24143 24144@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 24145@anchor{gnat_rm/the_gnat_library id82}@anchor{36c}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{36d} 24146@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 24147 24148 24149@geindex GNAT.Heap_Sort_A (g-hesora.ads) 24150 24151@geindex Sorting 24152 24153Provides a general implementation of heap sort usable for sorting arbitrary 24154data items. Move and comparison procedures are provided by passing 24155access-to-procedure values. The algorithm used is a modified heap sort 24156that performs approximately N*log(N) comparisons in the worst case. 24157This differs from @code{GNAT.Heap_Sort} in having a less convenient 24158interface, but may be slightly more efficient. 24159 24160@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 24161@anchor{gnat_rm/the_gnat_library id83}@anchor{36e}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{36f} 24162@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 24163 24164 24165@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 24166 24167@geindex Sorting 24168 24169Similar to @code{Heap_Sort_A} except that the move and sorting procedures 24170are provided as generic parameters, this improves efficiency, especially 24171if the procedures can be inlined, at the expense of duplicating code for 24172multiple instantiations. 24173 24174@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 24175@anchor{gnat_rm/the_gnat_library id84}@anchor{370}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{371} 24176@section @code{GNAT.HTable} (@code{g-htable.ads}) 24177 24178 24179@geindex GNAT.HTable (g-htable.ads) 24180 24181@geindex Hash tables 24182 24183A generic implementation of hash tables that can be used to hash arbitrary 24184data. Provides two approaches, one a simple static approach, and the other 24185allowing arbitrary dynamic hash tables. 24186 24187@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 24188@anchor{gnat_rm/the_gnat_library id85}@anchor{372}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{373} 24189@section @code{GNAT.IO} (@code{g-io.ads}) 24190 24191 24192@geindex GNAT.IO (g-io.ads) 24193 24194@geindex Simple I/O 24195 24196@geindex Input/Output facilities 24197 24198A simple preelaborable input-output package that provides a subset of 24199simple Text_IO functions for reading characters and strings from 24200Standard_Input, and writing characters, strings and integers to either 24201Standard_Output or Standard_Error. 24202 24203@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 24204@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{374}@anchor{gnat_rm/the_gnat_library id86}@anchor{375} 24205@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) 24206 24207 24208@geindex GNAT.IO_Aux (g-io_aux.ads) 24209 24210@geindex Text_IO 24211 24212@geindex Input/Output facilities 24213 24214Provides some auxiliary functions for use with Text_IO, including a test 24215for whether a file exists, and functions for reading a line of text. 24216 24217@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 24218@anchor{gnat_rm/the_gnat_library id87}@anchor{376}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{377} 24219@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) 24220 24221 24222@geindex GNAT.Lock_Files (g-locfil.ads) 24223 24224@geindex File locking 24225 24226@geindex Locking using files 24227 24228Provides a general interface for using files as locks. Can be used for 24229providing program level synchronization. 24230 24231@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 24232@anchor{gnat_rm/the_gnat_library id88}@anchor{378}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{379} 24233@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 24234 24235 24236@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 24237 24238@geindex Random number generation 24239 24240The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 24241a modified version of the Blum-Blum-Shub generator. 24242 24243@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 24244@anchor{gnat_rm/the_gnat_library id89}@anchor{37a}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{37b} 24245@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 24246 24247 24248@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 24249 24250@geindex Random number generation 24251 24252The original implementation of @code{Ada.Numerics.Float_Random}. Uses 24253a modified version of the Blum-Blum-Shub generator. 24254 24255@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 24256@anchor{gnat_rm/the_gnat_library id90}@anchor{37c}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{37d} 24257@section @code{GNAT.MD5} (@code{g-md5.ads}) 24258 24259 24260@geindex GNAT.MD5 (g-md5.ads) 24261 24262@geindex Message Digest MD5 24263 24264Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 24265the HMAC-MD5 message authentication function as described in RFC 2104 and 24266FIPS PUB 198. 24267 24268@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 24269@anchor{gnat_rm/the_gnat_library id91}@anchor{37e}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{37f} 24270@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) 24271 24272 24273@geindex GNAT.Memory_Dump (g-memdum.ads) 24274 24275@geindex Dump Memory 24276 24277Provides a convenient routine for dumping raw memory to either the 24278standard output or standard error files. Uses GNAT.IO for actual 24279output. 24280 24281@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 24282@anchor{gnat_rm/the_gnat_library id92}@anchor{380}@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{381} 24283@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 24284 24285 24286@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 24287 24288@geindex Exception 24289@geindex obtaining most recent 24290 24291Provides access to the most recently raised exception. Can be used for 24292various logging purposes, including duplicating functionality of some 24293Ada 83 implementation dependent extensions. 24294 24295@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 24296@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{382}@anchor{gnat_rm/the_gnat_library id93}@anchor{383} 24297@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) 24298 24299 24300@geindex GNAT.OS_Lib (g-os_lib.ads) 24301 24302@geindex Operating System interface 24303 24304@geindex Spawn capability 24305 24306Provides a range of target independent operating system interface functions, 24307including time/date management, file operations, subprocess management, 24308including a portable spawn procedure, and access to environment variables 24309and error return codes. 24310 24311@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 24312@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{384}@anchor{gnat_rm/the_gnat_library id94}@anchor{385} 24313@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 24314 24315 24316@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 24317 24318@geindex Hash functions 24319 24320Provides a generator of static minimal perfect hash functions. No 24321collisions occur and each item can be retrieved from the table in one 24322probe (perfect property). The hash table size corresponds to the exact 24323size of the key set and no larger (minimal property). The key set has to 24324be know in advance (static property). The hash functions are also order 24325preserving. If w2 is inserted after w1 in the generator, their 24326hashcode are in the same order. These hashing functions are very 24327convenient for use with realtime applications. 24328 24329@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 24330@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id95}@anchor{387} 24331@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) 24332 24333 24334@geindex GNAT.Random_Numbers (g-rannum.ads) 24335 24336@geindex Random number generation 24337 24338Provides random number capabilities which extend those available in the 24339standard Ada library and are more convenient to use. 24340 24341@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 24342@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{251}@anchor{gnat_rm/the_gnat_library id96}@anchor{388} 24343@section @code{GNAT.Regexp} (@code{g-regexp.ads}) 24344 24345 24346@geindex GNAT.Regexp (g-regexp.ads) 24347 24348@geindex Regular expressions 24349 24350@geindex Pattern matching 24351 24352A simple implementation of regular expressions, using a subset of regular 24353expression syntax copied from familiar Unix style utilities. This is the 24354simplest of the three pattern matching packages provided, and is particularly 24355suitable for 'file globbing' applications. 24356 24357@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 24358@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id97}@anchor{38a} 24359@section @code{GNAT.Registry} (@code{g-regist.ads}) 24360 24361 24362@geindex GNAT.Registry (g-regist.ads) 24363 24364@geindex Windows Registry 24365 24366This is a high level binding to the Windows registry. It is possible to 24367do simple things like reading a key value, creating a new key. For full 24368registry API, but at a lower level of abstraction, refer to the Win32.Winreg 24369package provided with the Win32Ada binding 24370 24371@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 24372@anchor{gnat_rm/the_gnat_library id98}@anchor{38b}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{38c} 24373@section @code{GNAT.Regpat} (@code{g-regpat.ads}) 24374 24375 24376@geindex GNAT.Regpat (g-regpat.ads) 24377 24378@geindex Regular expressions 24379 24380@geindex Pattern matching 24381 24382A complete implementation of Unix-style regular expression matching, copied 24383from the original V7 style regular expression library written in C by 24384Henry Spencer (and binary compatible with this C library). 24385 24386@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 24387@anchor{gnat_rm/the_gnat_library id99}@anchor{38d}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{38e} 24388@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 24389 24390 24391@geindex GNAT.Rewrite_Data (g-rewdat.ads) 24392 24393@geindex Rewrite data 24394 24395A unit to rewrite on-the-fly string occurrences in a stream of 24396data. The implementation has a very minimal memory footprint as the 24397full content to be processed is not loaded into memory all at once. This makes 24398this interface usable for large files or socket streams. 24399 24400@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 24401@anchor{gnat_rm/the_gnat_library id100}@anchor{38f}@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{390} 24402@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 24403 24404 24405@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 24406 24407@geindex Secondary Stack Info 24408 24409Provide the capability to query the high water mark of the current task's 24410secondary stack. 24411 24412@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 24413@anchor{gnat_rm/the_gnat_library id101}@anchor{391}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{392} 24414@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) 24415 24416 24417@geindex GNAT.Semaphores (g-semaph.ads) 24418 24419@geindex Semaphores 24420 24421Provides classic counting and binary semaphores using protected types. 24422 24423@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 24424@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{393}@anchor{gnat_rm/the_gnat_library id102}@anchor{394} 24425@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) 24426 24427 24428@geindex GNAT.Serial_Communications (g-sercom.ads) 24429 24430@geindex Serial_Communications 24431 24432Provides a simple interface to send and receive data over a serial 24433port. This is only supported on GNU/Linux and Windows. 24434 24435@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 24436@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{395}@anchor{gnat_rm/the_gnat_library id103}@anchor{396} 24437@section @code{GNAT.SHA1} (@code{g-sha1.ads}) 24438 24439 24440@geindex GNAT.SHA1 (g-sha1.ads) 24441 24442@geindex Secure Hash Algorithm SHA-1 24443 24444Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 24445and RFC 3174, and the HMAC-SHA1 message authentication function as described 24446in RFC 2104 and FIPS PUB 198. 24447 24448@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 24449@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{397}@anchor{gnat_rm/the_gnat_library id104}@anchor{398} 24450@section @code{GNAT.SHA224} (@code{g-sha224.ads}) 24451 24452 24453@geindex GNAT.SHA224 (g-sha224.ads) 24454 24455@geindex Secure Hash Algorithm SHA-224 24456 24457Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 24458and the HMAC-SHA224 message authentication function as described 24459in RFC 2104 and FIPS PUB 198. 24460 24461@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 24462@anchor{gnat_rm/the_gnat_library id105}@anchor{399}@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{39a} 24463@section @code{GNAT.SHA256} (@code{g-sha256.ads}) 24464 24465 24466@geindex GNAT.SHA256 (g-sha256.ads) 24467 24468@geindex Secure Hash Algorithm SHA-256 24469 24470Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 24471and the HMAC-SHA256 message authentication function as described 24472in RFC 2104 and FIPS PUB 198. 24473 24474@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 24475@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{39b}@anchor{gnat_rm/the_gnat_library id106}@anchor{39c} 24476@section @code{GNAT.SHA384} (@code{g-sha384.ads}) 24477 24478 24479@geindex GNAT.SHA384 (g-sha384.ads) 24480 24481@geindex Secure Hash Algorithm SHA-384 24482 24483Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 24484and the HMAC-SHA384 message authentication function as described 24485in RFC 2104 and FIPS PUB 198. 24486 24487@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 24488@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{39d}@anchor{gnat_rm/the_gnat_library id107}@anchor{39e} 24489@section @code{GNAT.SHA512} (@code{g-sha512.ads}) 24490 24491 24492@geindex GNAT.SHA512 (g-sha512.ads) 24493 24494@geindex Secure Hash Algorithm SHA-512 24495 24496Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 24497and the HMAC-SHA512 message authentication function as described 24498in RFC 2104 and FIPS PUB 198. 24499 24500@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24501@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{39f}@anchor{gnat_rm/the_gnat_library id108}@anchor{3a0} 24502@section @code{GNAT.Signals} (@code{g-signal.ads}) 24503 24504 24505@geindex GNAT.Signals (g-signal.ads) 24506 24507@geindex Signals 24508 24509Provides the ability to manipulate the blocked status of signals on supported 24510targets. 24511 24512@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24513@anchor{gnat_rm/the_gnat_library id109}@anchor{3a1}@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a2} 24514@section @code{GNAT.Sockets} (@code{g-socket.ads}) 24515 24516 24517@geindex GNAT.Sockets (g-socket.ads) 24518 24519@geindex Sockets 24520 24521A high level and portable interface to develop sockets based applications. 24522This package is based on the sockets thin binding found in 24523@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 24524on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24525the LynxOS cross port. 24526 24527@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24528@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a3}@anchor{gnat_rm/the_gnat_library id110}@anchor{3a4} 24529@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) 24530 24531 24532@geindex GNAT.Source_Info (g-souinf.ads) 24533 24534@geindex Source Information 24535 24536Provides subprograms that give access to source code information known at 24537compile time, such as the current file name and line number. Also provides 24538subprograms yielding the date and time of the current compilation (like the 24539C macros @code{__DATE__} and @code{__TIME__}) 24540 24541@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 24542@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3a5}@anchor{gnat_rm/the_gnat_library id111}@anchor{3a6} 24543@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) 24544 24545 24546@geindex GNAT.Spelling_Checker (g-speche.ads) 24547 24548@geindex Spell checking 24549 24550Provides a function for determining whether one string is a plausible 24551near misspelling of another string. 24552 24553@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 24554@anchor{gnat_rm/the_gnat_library id112}@anchor{3a7}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3a8} 24555@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 24556 24557 24558@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 24559 24560@geindex Spell checking 24561 24562Provides a generic function that can be instantiated with a string type for 24563determining whether one string is a plausible near misspelling of another 24564string. 24565 24566@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 24567@anchor{gnat_rm/the_gnat_library id113}@anchor{3a9}@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3aa} 24568@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 24569 24570 24571@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 24572 24573@geindex SPITBOL pattern matching 24574 24575@geindex Pattern matching 24576 24577A complete implementation of SNOBOL4 style pattern matching. This is the 24578most elaborate of the pattern matching packages provided. It fully duplicates 24579the SNOBOL4 dynamic pattern construction and matching capabilities, using the 24580efficient algorithm developed by Robert Dewar for the SPITBOL system. 24581 24582@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 24583@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3ab}@anchor{gnat_rm/the_gnat_library id114}@anchor{3ac} 24584@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) 24585 24586 24587@geindex GNAT.Spitbol (g-spitbo.ads) 24588 24589@geindex SPITBOL interface 24590 24591The top level package of the collection of SPITBOL-style functionality, this 24592package provides basic SNOBOL4 string manipulation functions, such as 24593Pad, Reverse, Trim, Substr capability, as well as a generic table function 24594useful for constructing arbitrary mappings from strings in the style of 24595the SNOBOL4 TABLE function. 24596 24597@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 24598@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3ad}@anchor{gnat_rm/the_gnat_library id115}@anchor{3ae} 24599@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 24600 24601 24602@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 24603 24604@geindex Sets of strings 24605 24606@geindex SPITBOL Tables 24607 24608A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24609for type @code{Standard.Boolean}, giving an implementation of sets of 24610string values. 24611 24612@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 24613@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3af}@anchor{gnat_rm/the_gnat_library id116}@anchor{3b0} 24614@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 24615 24616 24617@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 24618 24619@geindex Integer maps 24620 24621@geindex Maps 24622 24623@geindex SPITBOL Tables 24624 24625A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24626for type @code{Standard.Integer}, giving an implementation of maps 24627from string to integer values. 24628 24629@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 24630@anchor{gnat_rm/the_gnat_library id117}@anchor{3b1}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b2} 24631@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 24632 24633 24634@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 24635 24636@geindex String maps 24637 24638@geindex Maps 24639 24640@geindex SPITBOL Tables 24641 24642A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 24643a variable length string type, giving an implementation of general 24644maps from strings to strings. 24645 24646@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 24647@anchor{gnat_rm/the_gnat_library id118}@anchor{3b3}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b4} 24648@section @code{GNAT.SSE} (@code{g-sse.ads}) 24649 24650 24651@geindex GNAT.SSE (g-sse.ads) 24652 24653Root of a set of units aimed at offering Ada bindings to a subset of 24654the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 24655targets. It exposes vector component types together with a general 24656introduction to the binding contents and use. 24657 24658@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library 24659@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3b5}@anchor{gnat_rm/the_gnat_library id119}@anchor{3b6} 24660@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 24661 24662 24663@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 24664 24665SSE vector types for use with SSE related intrinsics. 24666 24667@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 24668@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3b7}@anchor{gnat_rm/the_gnat_library id120}@anchor{3b8} 24669@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) 24670 24671 24672@geindex GNAT.String_Hash (g-strhas.ads) 24673 24674@geindex Hash functions 24675 24676Provides a generic hash function working on arrays of scalars. Both the scalar 24677type and the hash result type are parameters. 24678 24679@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library 24680@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3b9}@anchor{gnat_rm/the_gnat_library id121}@anchor{3ba} 24681@section @code{GNAT.Strings} (@code{g-string.ads}) 24682 24683 24684@geindex GNAT.Strings (g-string.ads) 24685 24686Common String access types and related subprograms. Basically it 24687defines a string access and an array of string access types. 24688 24689@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 24690@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3bb}@anchor{gnat_rm/the_gnat_library id122}@anchor{3bc} 24691@section @code{GNAT.String_Split} (@code{g-strspl.ads}) 24692 24693 24694@geindex GNAT.String_Split (g-strspl.ads) 24695 24696@geindex String splitter 24697 24698Useful string manipulation routines: given a set of separators, split 24699a string wherever the separators appear, and provide direct access 24700to the resulting slices. This package is instantiated from 24701@code{GNAT.Array_Split}. 24702 24703@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 24704@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3bd}@anchor{gnat_rm/the_gnat_library id123}@anchor{3be} 24705@section @code{GNAT.Table} (@code{g-table.ads}) 24706 24707 24708@geindex GNAT.Table (g-table.ads) 24709 24710@geindex Table implementation 24711 24712@geindex Arrays 24713@geindex extendable 24714 24715A generic package providing a single dimension array abstraction where the 24716length of the array can be dynamically modified. 24717 24718This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 24719except that this package declares a single instance of the table type, 24720while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 24721used to define dynamic instances of the table. 24722 24723@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 24724@anchor{gnat_rm/the_gnat_library id124}@anchor{3bf}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3c0} 24725@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) 24726 24727 24728@geindex GNAT.Task_Lock (g-tasloc.ads) 24729 24730@geindex Task synchronization 24731 24732@geindex Task locking 24733 24734@geindex Locking 24735 24736A very simple facility for locking and unlocking sections of code using a 24737single global task lock. Appropriate for use in situations where contention 24738between tasks is very rarely expected. 24739 24740@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 24741@anchor{gnat_rm/the_gnat_library id125}@anchor{3c1}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c2} 24742@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) 24743 24744 24745@geindex GNAT.Time_Stamp (g-timsta.ads) 24746 24747@geindex Time stamp 24748 24749@geindex Current time 24750 24751Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 24752represents the current date and time in ISO 8601 format. This is a very simple 24753routine with minimal code and there are no dependencies on any other unit. 24754 24755@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 24756@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c3}@anchor{gnat_rm/the_gnat_library id126}@anchor{3c4} 24757@section @code{GNAT.Threads} (@code{g-thread.ads}) 24758 24759 24760@geindex GNAT.Threads (g-thread.ads) 24761 24762@geindex Foreign threads 24763 24764@geindex Threads 24765@geindex foreign 24766 24767Provides facilities for dealing with foreign threads which need to be known 24768by the GNAT run-time system. Consult the documentation of this package for 24769further details if your program has threads that are created by a non-Ada 24770environment which then accesses Ada code. 24771 24772@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 24773@anchor{gnat_rm/the_gnat_library id127}@anchor{3c5}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3c6} 24774@section @code{GNAT.Traceback} (@code{g-traceb.ads}) 24775 24776 24777@geindex GNAT.Traceback (g-traceb.ads) 24778 24779@geindex Trace back facilities 24780 24781Provides a facility for obtaining non-symbolic traceback information, useful 24782in various debugging situations. 24783 24784@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 24785@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3c7}@anchor{gnat_rm/the_gnat_library id128}@anchor{3c8} 24786@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 24787 24788 24789@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 24790 24791@geindex Trace back facilities 24792 24793@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 24794@anchor{gnat_rm/the_gnat_library id129}@anchor{3c9}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3ca} 24795@section @code{GNAT.UTF_32} (@code{g-table.ads}) 24796 24797 24798@geindex GNAT.UTF_32 (g-table.ads) 24799 24800@geindex Wide character codes 24801 24802This is a package intended to be used in conjunction with the 24803@code{Wide_Character} type in Ada 95 and the 24804@code{Wide_Wide_Character} type in Ada 2005 (available 24805in @code{GNAT} in Ada 2005 mode). This package contains 24806Unicode categorization routines, as well as lexical 24807categorization routines corresponding to the Ada 2005 24808lexical rules for identifiers and strings, and also a 24809lower case to upper case fold routine corresponding to 24810the Ada 2005 rules for identifier equivalence. 24811 24812@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 24813@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3cb}@anchor{gnat_rm/the_gnat_library id130}@anchor{3cc} 24814@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 24815 24816 24817@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 24818 24819@geindex Spell checking 24820 24821Provides a function for determining whether one wide wide string is a plausible 24822near misspelling of another wide wide string, where the strings are represented 24823using the UTF_32_String type defined in System.Wch_Cnv. 24824 24825@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 24826@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3cd}@anchor{gnat_rm/the_gnat_library id131}@anchor{3ce} 24827@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 24828 24829 24830@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 24831 24832@geindex Spell checking 24833 24834Provides a function for determining whether one wide string is a plausible 24835near misspelling of another wide string. 24836 24837@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 24838@anchor{gnat_rm/the_gnat_library id132}@anchor{3cf}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3d0} 24839@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 24840 24841 24842@geindex GNAT.Wide_String_Split (g-wistsp.ads) 24843 24844@geindex Wide_String splitter 24845 24846Useful wide string manipulation routines: given a set of separators, split 24847a wide string wherever the separators appear, and provide direct access 24848to the resulting slices. This package is instantiated from 24849@code{GNAT.Array_Split}. 24850 24851@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 24852@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d1}@anchor{gnat_rm/the_gnat_library id133}@anchor{3d2} 24853@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 24854 24855 24856@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 24857 24858@geindex Spell checking 24859 24860Provides a function for determining whether one wide wide string is a plausible 24861near misspelling of another wide wide string. 24862 24863@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 24864@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d3}@anchor{gnat_rm/the_gnat_library id134}@anchor{3d4} 24865@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 24866 24867 24868@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 24869 24870@geindex Wide_Wide_String splitter 24871 24872Useful wide wide string manipulation routines: given a set of separators, split 24873a wide wide string wherever the separators appear, and provide direct access 24874to the resulting slices. This package is instantiated from 24875@code{GNAT.Array_Split}. 24876 24877@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 24878@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d5}@anchor{gnat_rm/the_gnat_library id135}@anchor{3d6} 24879@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) 24880 24881 24882@geindex Interfaces.C.Extensions (i-cexten.ads) 24883 24884This package contains additional C-related definitions, intended 24885for use with either manually or automatically generated bindings 24886to C libraries. 24887 24888@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 24889@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3d7}@anchor{gnat_rm/the_gnat_library id136}@anchor{3d8} 24890@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) 24891 24892 24893@geindex Interfaces.C.Streams (i-cstrea.ads) 24894 24895@geindex C streams 24896@geindex interfacing 24897 24898This package is a binding for the most commonly used operations 24899on C streams. 24900 24901@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 24902@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3d9}@anchor{gnat_rm/the_gnat_library id137}@anchor{3da} 24903@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 24904 24905 24906@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 24907 24908@geindex IBM Packed Format 24909 24910@geindex Packed Decimal 24911 24912This package provides a set of routines for conversions to and 24913from a packed decimal format compatible with that used on IBM 24914mainframes. 24915 24916@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 24917@anchor{gnat_rm/the_gnat_library id138}@anchor{3db}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3dc} 24918@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) 24919 24920 24921@geindex Interfaces.VxWorks (i-vxwork.ads) 24922 24923@geindex Interfacing to VxWorks 24924 24925@geindex VxWorks 24926@geindex interfacing 24927 24928This package provides a limited binding to the VxWorks API. 24929In particular, it interfaces with the 24930VxWorks hardware interrupt facilities. 24931 24932@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 24933@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3dd}@anchor{gnat_rm/the_gnat_library id139}@anchor{3de} 24934@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) 24935 24936 24937@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) 24938 24939@geindex Interfacing to VxWorks 24940 24941@geindex VxWorks 24942@geindex interfacing 24943 24944This package provides a way for users to replace the use of 24945intConnect() with a custom routine for installing interrupt 24946handlers. 24947 24948@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library 24949@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3df}@anchor{gnat_rm/the_gnat_library id140}@anchor{3e0} 24950@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 24951 24952 24953@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 24954 24955@geindex Interfacing to VxWorks' I/O 24956 24957@geindex VxWorks 24958@geindex I/O interfacing 24959 24960@geindex VxWorks 24961@geindex Get_Immediate 24962 24963@geindex Get_Immediate 24964@geindex VxWorks 24965 24966This package provides a binding to the ioctl (IO/Control) 24967function of VxWorks, defining a set of option values and 24968function codes. A particular use of this package is 24969to enable the use of Get_Immediate under VxWorks. 24970 24971@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 24972@anchor{gnat_rm/the_gnat_library id141}@anchor{3e1}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e2} 24973@section @code{System.Address_Image} (@code{s-addima.ads}) 24974 24975 24976@geindex System.Address_Image (s-addima.ads) 24977 24978@geindex Address image 24979 24980@geindex Image 24981@geindex of an address 24982 24983This function provides a useful debugging 24984function that gives an (implementation dependent) 24985string which identifies an address. 24986 24987@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 24988@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e3}@anchor{gnat_rm/the_gnat_library id142}@anchor{3e4} 24989@section @code{System.Assertions} (@code{s-assert.ads}) 24990 24991 24992@geindex System.Assertions (s-assert.ads) 24993 24994@geindex Assertions 24995 24996@geindex Assert_Failure 24997@geindex exception 24998 24999This package provides the declaration of the exception raised 25000by an run-time assertion failure, as well as the routine that 25001is used internally to raise this assertion. 25002 25003@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 25004@anchor{gnat_rm/the_gnat_library id143}@anchor{3e5}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3e6} 25005@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) 25006 25007 25008@geindex System.Atomic_Counters (s-atocou.ads) 25009 25010This package provides the declaration of an atomic counter type, 25011together with efficient routines (using hardware 25012synchronization primitives) for incrementing, decrementing, 25013and testing of these counters. This package is implemented 25014on most targets, including all Alpha, ia64, PowerPC, SPARC V9, 25015x86, and x86_64 platforms. 25016 25017@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 25018@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3e7}@anchor{gnat_rm/the_gnat_library id144}@anchor{3e8} 25019@section @code{System.Memory} (@code{s-memory.ads}) 25020 25021 25022@geindex System.Memory (s-memory.ads) 25023 25024@geindex Memory allocation 25025 25026This package provides the interface to the low level routines used 25027by the generated code for allocation and freeing storage for the 25028default storage pool (analogous to the C routines malloc and free. 25029It also provides a reallocation interface analogous to the C routine 25030realloc. The body of this unit may be modified to provide alternative 25031allocation mechanisms for the default pool, and in addition, direct 25032calls to this unit may be made for low level allocation uses (for 25033example see the body of @code{GNAT.Tables}). 25034 25035@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 25036@anchor{gnat_rm/the_gnat_library id145}@anchor{3e9}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3ea} 25037@section @code{System.Multiprocessors} (@code{s-multip.ads}) 25038 25039 25040@geindex System.Multiprocessors (s-multip.ads) 25041 25042@geindex Multiprocessor interface 25043 25044This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25045in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25046technically an implementation-defined addition). 25047 25048@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 25049@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3eb}@anchor{gnat_rm/the_gnat_library id146}@anchor{3ec} 25050@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 25051 25052 25053@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 25054 25055@geindex Multiprocessor interface 25056 25057This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25058in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25059technically an implementation-defined addition). 25060 25061@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 25062@anchor{gnat_rm/the_gnat_library id147}@anchor{3ed}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3ee} 25063@section @code{System.Partition_Interface} (@code{s-parint.ads}) 25064 25065 25066@geindex System.Partition_Interface (s-parint.ads) 25067 25068@geindex Partition interfacing functions 25069 25070This package provides facilities for partition interfacing. It 25071is used primarily in a distribution context when using Annex E 25072with @code{GLADE}. 25073 25074@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 25075@anchor{gnat_rm/the_gnat_library id148}@anchor{3ef}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3f0} 25076@section @code{System.Pool_Global} (@code{s-pooglo.ads}) 25077 25078 25079@geindex System.Pool_Global (s-pooglo.ads) 25080 25081@geindex Storage pool 25082@geindex global 25083 25084@geindex Global storage pool 25085 25086This package provides a storage pool that is equivalent to the default 25087storage pool used for access types for which no pool is specifically 25088declared. It uses malloc/free to allocate/free and does not attempt to 25089do any automatic reclamation. 25090 25091@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 25092@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f1}@anchor{gnat_rm/the_gnat_library id149}@anchor{3f2} 25093@section @code{System.Pool_Local} (@code{s-pooloc.ads}) 25094 25095 25096@geindex System.Pool_Local (s-pooloc.ads) 25097 25098@geindex Storage pool 25099@geindex local 25100 25101@geindex Local storage pool 25102 25103This package provides a storage pool that is intended for use with locally 25104defined access types. It uses malloc/free for allocate/free, and maintains 25105a list of allocated blocks, so that all storage allocated for the pool can 25106be freed automatically when the pool is finalized. 25107 25108@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 25109@anchor{gnat_rm/the_gnat_library id150}@anchor{3f3}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f4} 25110@section @code{System.Restrictions} (@code{s-restri.ads}) 25111 25112 25113@geindex System.Restrictions (s-restri.ads) 25114 25115@geindex Run-time restrictions access 25116 25117This package provides facilities for accessing at run time 25118the status of restrictions specified at compile time for 25119the partition. Information is available both with regard 25120to actual restrictions specified, and with regard to 25121compiler determined information on which restrictions 25122are violated by one or more packages in the partition. 25123 25124@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 25125@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f5}@anchor{gnat_rm/the_gnat_library id151}@anchor{3f6} 25126@section @code{System.Rident} (@code{s-rident.ads}) 25127 25128 25129@geindex System.Rident (s-rident.ads) 25130 25131@geindex Restrictions definitions 25132 25133This package provides definitions of the restrictions 25134identifiers supported by GNAT, and also the format of 25135the restrictions provided in package System.Restrictions. 25136It is not normally necessary to @code{with} this generic package 25137since the necessary instantiation is included in 25138package System.Restrictions. 25139 25140@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 25141@anchor{gnat_rm/the_gnat_library id152}@anchor{3f7}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3f8} 25142@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 25143 25144 25145@geindex System.Strings.Stream_Ops (s-ststop.ads) 25146 25147@geindex Stream operations 25148 25149@geindex String stream operations 25150 25151This package provides a set of stream subprograms for standard string types. 25152It is intended primarily to support implicit use of such subprograms when 25153stream attributes are applied to string types, but the subprograms in this 25154package can be used directly by application programs. 25155 25156@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 25157@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3f9}@anchor{gnat_rm/the_gnat_library id153}@anchor{3fa} 25158@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) 25159 25160 25161@geindex System.Unsigned_Types (s-unstyp.ads) 25162 25163This package contains definitions of standard unsigned types that 25164correspond in size to the standard signed types declared in Standard, 25165and (unlike the types in Interfaces) have corresponding names. It 25166also contains some related definitions for other specialized types 25167used by the compiler in connection with packed array types. 25168 25169@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 25170@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3fb}@anchor{gnat_rm/the_gnat_library id154}@anchor{3fc} 25171@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) 25172 25173 25174@geindex System.Wch_Cnv (s-wchcnv.ads) 25175 25176@geindex Wide Character 25177@geindex Representation 25178 25179@geindex Wide String 25180@geindex Conversion 25181 25182@geindex Representation of wide characters 25183 25184This package provides routines for converting between 25185wide and wide wide characters and a representation as a value of type 25186@code{Standard.String}, using a specified wide character 25187encoding method. It uses definitions in 25188package @code{System.Wch_Con}. 25189 25190@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 25191@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3fd}@anchor{gnat_rm/the_gnat_library id155}@anchor{3fe} 25192@section @code{System.Wch_Con} (@code{s-wchcon.ads}) 25193 25194 25195@geindex System.Wch_Con (s-wchcon.ads) 25196 25197This package provides definitions and descriptions of 25198the various methods used for encoding wide characters 25199in ordinary strings. These definitions are used by 25200the package @code{System.Wch_Cnv}. 25201 25202@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 25203@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3ff}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{400} 25204@chapter Interfacing to Other Languages 25205 25206 25207The facilities in Annex B of the Ada Reference Manual are fully 25208implemented in GNAT, and in addition, a full interface to C++ is 25209provided. 25210 25211@menu 25212* Interfacing to C:: 25213* Interfacing to C++:: 25214* Interfacing to COBOL:: 25215* Interfacing to Fortran:: 25216* Interfacing to non-GNAT Ada code:: 25217 25218@end menu 25219 25220@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 25221@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{401}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{402} 25222@section Interfacing to C 25223 25224 25225Interfacing to C with GNAT can use one of two approaches: 25226 25227 25228@itemize * 25229 25230@item 25231The types in the package @code{Interfaces.C} may be used. 25232 25233@item 25234Standard Ada types may be used directly. This may be less portable to 25235other compilers, but will work on all GNAT compilers, which guarantee 25236correspondence between the C and Ada types. 25237@end itemize 25238 25239Pragma @code{Convention C} may be applied to Ada types, but mostly has no 25240effect, since this is the default. The following table shows the 25241correspondence between Ada scalar types and the corresponding C types. 25242 25243 25244@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 25245@headitem 25246 25247Ada Type 25248 25249@tab 25250 25251C Type 25252 25253@item 25254 25255@code{Integer} 25256 25257@tab 25258 25259@code{int} 25260 25261@item 25262 25263@code{Short_Integer} 25264 25265@tab 25266 25267@code{short} 25268 25269@item 25270 25271@code{Short_Short_Integer} 25272 25273@tab 25274 25275@code{signed char} 25276 25277@item 25278 25279@code{Long_Integer} 25280 25281@tab 25282 25283@code{long} 25284 25285@item 25286 25287@code{Long_Long_Integer} 25288 25289@tab 25290 25291@code{long long} 25292 25293@item 25294 25295@code{Short_Float} 25296 25297@tab 25298 25299@code{float} 25300 25301@item 25302 25303@code{Float} 25304 25305@tab 25306 25307@code{float} 25308 25309@item 25310 25311@code{Long_Float} 25312 25313@tab 25314 25315@code{double} 25316 25317@item 25318 25319@code{Long_Long_Float} 25320 25321@tab 25322 25323This is the longest floating-point type supported by the hardware. 25324 25325@end multitable 25326 25327 25328Additionally, there are the following general correspondences between Ada 25329and C types: 25330 25331 25332@itemize * 25333 25334@item 25335Ada enumeration types map to C enumeration types directly if pragma 25336@code{Convention C} is specified, which causes them to have int 25337length. Without pragma @code{Convention C}, Ada enumeration types map to 253388, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, 25339@code{int}, respectively) depending on the number of values passed. 25340This is the only case in which pragma @code{Convention C} affects the 25341representation of an Ada type. 25342 25343@item 25344Ada access types map to C pointers, except for the case of pointers to 25345unconstrained types in Ada, which have no direct C equivalent. 25346 25347@item 25348Ada arrays map directly to C arrays. 25349 25350@item 25351Ada records map directly to C structures. 25352 25353@item 25354Packed Ada records map to C structures where all members are bit fields 25355of the length corresponding to the @code{type'Size} value in Ada. 25356@end itemize 25357 25358@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 25359@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{403}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{45} 25360@section Interfacing to C++ 25361 25362 25363The interface to C++ makes use of the following pragmas, which are 25364primarily intended to be constructed automatically using a binding generator 25365tool, although it is possible to construct them by hand. 25366 25367Using these pragmas it is possible to achieve complete 25368inter-operability between Ada tagged types and C++ class definitions. 25369See @ref{7,,Implementation Defined Pragmas}, for more details. 25370 25371 25372@table @asis 25373 25374@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} 25375 25376The argument denotes an entity in the current declarative region that is 25377declared as a tagged or untagged record type. It indicates that the type 25378corresponds to an externally declared C++ class type, and is to be laid 25379out the same way that C++ would lay out the type. 25380 25381Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 25382for backward compatibility but its functionality is available 25383using pragma @code{Import} with @code{Convention} = @code{CPP}. 25384 25385@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} 25386 25387This pragma identifies an imported function (imported in the usual way 25388with pragma @code{Import}) as corresponding to a C++ constructor. 25389@end table 25390 25391A few restrictions are placed on the use of the @code{Access} attribute 25392in conjunction with subprograms subject to convention @code{CPP}: the 25393attribute may be used neither on primitive operations of a tagged 25394record type with convention @code{CPP}, imported or not, nor on 25395subprograms imported with pragma @code{CPP_Constructor}. 25396 25397In addition, C++ exceptions are propagated and can be handled in an 25398@code{others} choice of an exception handler. The corresponding Ada 25399occurrence has no message, and the simple name of the exception identity 25400contains @code{Foreign_Exception}. Finalization and awaiting dependent 25401tasks works properly when such foreign exceptions are propagated. 25402 25403It is also possible to import a C++ exception using the following syntax: 25404 25405@example 25406LOCAL_NAME : exception; 25407pragma Import (Cpp, 25408 [Entity =>] LOCAL_NAME, 25409 [External_Name =>] static_string_EXPRESSION); 25410@end example 25411 25412The @code{External_Name} is the name of the C++ RTTI symbol. You can then 25413cover a specific C++ exception in an exception handler. 25414 25415@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 25416@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{404}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{405} 25417@section Interfacing to COBOL 25418 25419 25420Interfacing to COBOL is achieved as described in section B.4 of 25421the Ada Reference Manual. 25422 25423@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 25424@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{406}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{407} 25425@section Interfacing to Fortran 25426 25427 25428Interfacing to Fortran is achieved as described in section B.5 of the 25429Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 25430multi-dimensional array causes the array to be stored in column-major 25431order as required for convenient interface to Fortran. 25432 25433@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 25434@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{408}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{409} 25435@section Interfacing to non-GNAT Ada code 25436 25437 25438It is possible to specify the convention @code{Ada} in a pragma 25439@code{Import} or pragma @code{Export}. However this refers to 25440the calling conventions used by GNAT, which may or may not be 25441similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 25442compiler to allow interoperation. 25443 25444If arguments types are kept simple, and if the foreign compiler generally 25445follows system calling conventions, then it may be possible to integrate 25446files compiled by other Ada compilers, provided that the elaboration 25447issues are adequately addressed (for example by eliminating the 25448need for any load time elaboration). 25449 25450In particular, GNAT running on VMS is designed to 25451be highly compatible with the DEC Ada 83 compiler, so this is one 25452case in which it is possible to import foreign units of this type, 25453provided that the data items passed are restricted to simple scalar 25454values or simple record types without variants, or simple array 25455types with fixed bounds. 25456 25457@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 25458@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{40a}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{40b} 25459@chapter Specialized Needs Annexes 25460 25461 25462Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 25463required in all implementations. However, as described in this chapter, 25464GNAT implements all of these annexes: 25465 25466 25467@table @asis 25468 25469@item @emph{Systems Programming (Annex C)} 25470 25471The Systems Programming Annex is fully implemented. 25472 25473@item @emph{Real-Time Systems (Annex D)} 25474 25475The Real-Time Systems Annex is fully implemented. 25476 25477@item @emph{Distributed Systems (Annex E)} 25478 25479Stub generation is fully implemented in the GNAT compiler. In addition, 25480a complete compatible PCS is available as part of the GLADE system, 25481a separate product. When the two 25482products are used in conjunction, this annex is fully implemented. 25483 25484@item @emph{Information Systems (Annex F)} 25485 25486The Information Systems annex is fully implemented. 25487 25488@item @emph{Numerics (Annex G)} 25489 25490The Numerics Annex is fully implemented. 25491 25492@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 25493 25494The Safety and Security Annex (termed the High-Integrity Systems Annex 25495in Ada 2005) is fully implemented. 25496@end table 25497 25498@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 25499@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{40c}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{40d} 25500@chapter Implementation of Specific Ada Features 25501 25502 25503This chapter describes the GNAT implementation of several Ada language 25504facilities. 25505 25506@menu 25507* Machine Code Insertions:: 25508* GNAT Implementation of Tasking:: 25509* GNAT Implementation of Shared Passive Packages:: 25510* Code Generation for Array Aggregates:: 25511* The Size of Discriminated Records with Default Discriminants:: 25512* Strict Conformance to the Ada Reference Manual:: 25513 25514@end menu 25515 25516@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 25517@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{164}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{40e} 25518@section Machine Code Insertions 25519 25520 25521@geindex Machine Code insertions 25522 25523Package @code{Machine_Code} provides machine code support as described 25524in the Ada Reference Manual in two separate forms: 25525 25526 25527@itemize * 25528 25529@item 25530Machine code statements, consisting of qualified expressions that 25531fit the requirements of RM section 13.8. 25532 25533@item 25534An intrinsic callable procedure, providing an alternative mechanism of 25535including machine instructions in a subprogram. 25536@end itemize 25537 25538The two features are similar, and both are closely related to the mechanism 25539provided by the asm instruction in the GNU C compiler. Full understanding 25540and use of the facilities in this package requires understanding the asm 25541instruction, see the section on Extended Asm in 25542@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 25543 25544Calls to the function @code{Asm} and the procedure @code{Asm} have identical 25545semantic restrictions and effects as described below. Both are provided so 25546that the procedure call can be used as a statement, and the function call 25547can be used to form a code_statement. 25548 25549Consider this C @code{asm} instruction: 25550 25551@example 25552asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 25553@end example 25554 25555The equivalent can be written for GNAT as: 25556 25557@example 25558Asm ("fsinx %1 %0", 25559 My_Float'Asm_Output ("=f", result), 25560 My_Float'Asm_Input ("f", angle)); 25561@end example 25562 25563The first argument to @code{Asm} is the assembler template, and is 25564identical to what is used in GNU C. This string must be a static 25565expression. The second argument is the output operand list. It is 25566either a single @code{Asm_Output} attribute reference, or a list of such 25567references enclosed in parentheses (technically an array aggregate of 25568such references). 25569 25570The @code{Asm_Output} attribute denotes a function that takes two 25571parameters. The first is a string, the second is the name of a variable 25572of the type designated by the attribute prefix. The first (string) 25573argument is required to be a static expression and designates the 25574constraint (see the section on Constraints in 25575@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 25576for the parameter; e.g., what kind of register is required. The second 25577argument is the variable to be written or updated with the 25578result. The possible values for constraint are the same as those used in 25579the RTL, and are dependent on the configuration file used to build the 25580GCC back end. If there are no output operands, then this argument may 25581either be omitted, or explicitly given as @code{No_Output_Operands}. 25582No support is provided for GNU C's symbolic names for output parameters. 25583 25584The second argument of @code{my_float'Asm_Output} functions as 25585though it were an @code{out} parameter, which is a little curious, but 25586all names have the form of expressions, so there is no syntactic 25587irregularity, even though normally functions would not be permitted 25588@code{out} parameters. The third argument is the list of input 25589operands. It is either a single @code{Asm_Input} attribute reference, or 25590a list of such references enclosed in parentheses (technically an array 25591aggregate of such references). 25592 25593The @code{Asm_Input} attribute denotes a function that takes two 25594parameters. The first is a string, the second is an expression of the 25595type designated by the prefix. The first (string) argument is required 25596to be a static expression, and is the constraint for the parameter, 25597(e.g., what kind of register is required). The second argument is the 25598value to be used as the input argument. The possible values for the 25599constraint are the same as those used in the RTL, and are dependent on 25600the configuration file used to built the GCC back end. 25601No support is provided for GNU C's symbolic names for input parameters. 25602 25603If there are no input operands, this argument may either be omitted, or 25604explicitly given as @code{No_Input_Operands}. The fourth argument, not 25605present in the above example, is a list of register names, called the 25606@emph{clobber} argument. This argument, if given, must be a static string 25607expression, and is a space or comma separated list of names of registers 25608that must be considered destroyed as a result of the @code{Asm} call. If 25609this argument is the null string (the default value), then the code 25610generator assumes that no additional registers are destroyed. 25611In addition to registers, the special clobbers @code{memory} and 25612@code{cc} as described in the GNU C docs are both supported. 25613 25614The fifth argument, not present in the above example, called the 25615@emph{volatile} argument, is by default @code{False}. It can be set to 25616the literal value @code{True} to indicate to the code generator that all 25617optimizations with respect to the instruction specified should be 25618suppressed, and in particular an instruction that has outputs 25619will still be generated, even if none of the outputs are 25620used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 25621for the full description. 25622Generally it is strongly advisable to use Volatile for any ASM statement 25623that is missing either input or output operands or to avoid unwanted 25624optimizations. A warning is generated if this advice is not followed. 25625 25626No support is provided for GNU C's @code{asm goto} feature. 25627 25628The @code{Asm} subprograms may be used in two ways. First the procedure 25629forms can be used anywhere a procedure call would be valid, and 25630correspond to what the RM calls 'intrinsic' routines. Such calls can 25631be used to intersperse machine instructions with other Ada statements. 25632Second, the function forms, which return a dummy value of the limited 25633private type @code{Asm_Insn}, can be used in code statements, and indeed 25634this is the only context where such calls are allowed. Code statements 25635appear as aggregates of the form: 25636 25637@example 25638Asm_Insn'(Asm (...)); 25639Asm_Insn'(Asm_Volatile (...)); 25640@end example 25641 25642In accordance with RM rules, such code statements are allowed only 25643within subprograms whose entire body consists of such statements. It is 25644not permissible to intermix such statements with other Ada statements. 25645 25646Typically the form using intrinsic procedure calls is more convenient 25647and more flexible. The code statement form is provided to meet the RM 25648suggestion that such a facility should be made available. The following 25649is the exact syntax of the call to @code{Asm}. As usual, if named notation 25650is used, the arguments may be given in arbitrary order, following the 25651normal rules for use of positional and named arguments: 25652 25653@example 25654ASM_CALL ::= Asm ( 25655 [Template =>] static_string_EXPRESSION 25656 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 25657 [,[Inputs =>] INPUT_OPERAND_LIST ] 25658 [,[Clobber =>] static_string_EXPRESSION ] 25659 [,[Volatile =>] static_boolean_EXPRESSION] ) 25660 25661OUTPUT_OPERAND_LIST ::= 25662 [PREFIX.]No_Output_Operands 25663| OUTPUT_OPERAND_ATTRIBUTE 25664| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 25665 25666OUTPUT_OPERAND_ATTRIBUTE ::= 25667 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 25668 25669INPUT_OPERAND_LIST ::= 25670 [PREFIX.]No_Input_Operands 25671| INPUT_OPERAND_ATTRIBUTE 25672| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 25673 25674INPUT_OPERAND_ATTRIBUTE ::= 25675 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 25676@end example 25677 25678The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 25679are declared in the package @code{Machine_Code} and must be referenced 25680according to normal visibility rules. In particular if there is no 25681@code{use} clause for this package, then appropriate package name 25682qualification is required. 25683 25684@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 25685@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{40f}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{410} 25686@section GNAT Implementation of Tasking 25687 25688 25689This chapter outlines the basic GNAT approach to tasking (in particular, 25690a multi-layered library for portability) and discusses issues related 25691to compliance with the Real-Time Systems Annex. 25692 25693@menu 25694* Mapping Ada Tasks onto the Underlying Kernel Threads:: 25695* Ensuring Compliance with the Real-Time Annex:: 25696* Support for Locking Policies:: 25697 25698@end menu 25699 25700@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 25701@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{411}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{412} 25702@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 25703 25704 25705GNAT's run-time support comprises two layers: 25706 25707 25708@itemize * 25709 25710@item 25711GNARL (GNAT Run-time Layer) 25712 25713@item 25714GNULL (GNAT Low-level Library) 25715@end itemize 25716 25717In GNAT, Ada's tasking services rely on a platform and OS independent 25718layer known as GNARL. This code is responsible for implementing the 25719correct semantics of Ada's task creation, rendezvous, protected 25720operations etc. 25721 25722GNARL decomposes Ada's tasking semantics into simpler lower level 25723operations such as create a thread, set the priority of a thread, 25724yield, create a lock, lock/unlock, etc. The spec for these low-level 25725operations constitutes GNULLI, the GNULL Interface. This interface is 25726directly inspired from the POSIX real-time API. 25727 25728If the underlying executive or OS implements the POSIX standard 25729faithfully, the GNULL Interface maps as is to the services offered by 25730the underlying kernel. Otherwise, some target dependent glue code maps 25731the services offered by the underlying kernel to the semantics expected 25732by GNARL. 25733 25734Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 25735key point is that each Ada task is mapped on a thread in the underlying 25736kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 25737 25738In addition Ada task priorities map onto the underlying thread priorities. 25739Mapping Ada tasks onto the underlying kernel threads has several advantages: 25740 25741 25742@itemize * 25743 25744@item 25745The underlying scheduler is used to schedule the Ada tasks. This 25746makes Ada tasks as efficient as kernel threads from a scheduling 25747standpoint. 25748 25749@item 25750Interaction with code written in C containing threads is eased 25751since at the lowest level Ada tasks and C threads map onto the same 25752underlying kernel concept. 25753 25754@item 25755When an Ada task is blocked during I/O the remaining Ada tasks are 25756able to proceed. 25757 25758@item 25759On multiprocessor systems Ada tasks can execute in parallel. 25760@end itemize 25761 25762Some threads libraries offer a mechanism to fork a new process, with the 25763child process duplicating the threads from the parent. 25764GNAT does not 25765support this functionality when the parent contains more than one task. 25766 25767@geindex Forking a new process 25768 25769@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 25770@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{413}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{414} 25771@subsection Ensuring Compliance with the Real-Time Annex 25772 25773 25774@geindex Real-Time Systems Annex compliance 25775 25776Although mapping Ada tasks onto 25777the underlying threads has significant advantages, it does create some 25778complications when it comes to respecting the scheduling semantics 25779specified in the real-time annex (Annex D). 25780 25781For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 25782scheduling policy states: 25783 25784@quotation 25785 25786@emph{When the active priority of a ready task that is not running 25787changes, or the setting of its base priority takes effect, the 25788task is removed from the ready queue for its old active priority 25789and is added at the tail of the ready queue for its new active 25790priority, except in the case where the active priority is lowered 25791due to the loss of inherited priority, in which case the task is 25792added at the head of the ready queue for its new active priority.} 25793@end quotation 25794 25795While most kernels do put tasks at the end of the priority queue when 25796a task changes its priority, (which respects the main 25797FIFO_Within_Priorities requirement), almost none keep a thread at the 25798beginning of its priority queue when its priority drops from the loss 25799of inherited priority. 25800 25801As a result most vendors have provided incomplete Annex D implementations. 25802 25803The GNAT run-time, has a nice cooperative solution to this problem 25804which ensures that accurate FIFO_Within_Priorities semantics are 25805respected. 25806 25807The principle is as follows. When an Ada task T is about to start 25808running, it checks whether some other Ada task R with the same 25809priority as T has been suspended due to the loss of priority 25810inheritance. If this is the case, T yields and is placed at the end of 25811its priority queue. When R arrives at the front of the queue it 25812executes. 25813 25814Note that this simple scheme preserves the relative order of the tasks 25815that were ready to execute in the priority queue where R has been 25816placed at the end. 25817 25818@c Support_for_Locking_Policies 25819 25820@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking 25821@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{415} 25822@subsection Support for Locking Policies 25823 25824 25825This section specifies which policies specified by pragma Locking_Policy 25826are supported on which platforms. 25827 25828GNAT supports the standard @code{Ceiling_Locking} policy, and the 25829implementation defined @code{Inheritance_Locking} and 25830@code{Concurrent_Readers_Locking} policies. 25831 25832@code{Ceiling_Locking} is supported on all platforms if the operating system 25833supports it. In particular, @code{Ceiling_Locking} is not supported on 25834VxWorks. 25835@code{Inheritance_Locking} is supported on 25836Linux, 25837Darwin (Mac OS X), 25838LynxOS 178, 25839and VxWorks. 25840@code{Concurrent_Readers_Locking} is supported on Linux. 25841 25842Notes about @code{Ceiling_Locking} on Linux: 25843If the process is running as 'root', ceiling locking is used. 25844If the capabilities facility is installed 25845("sudo apt-get --assume-yes install libcap-dev" on Ubuntu, 25846for example), 25847and the program is linked against that library 25848("-largs -lcap"), 25849and the executable file has the cap_sys_nice capability 25850("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"), 25851then ceiling locking is used. 25852Otherwise, the @code{Ceiling_Locking} policy is ignored. 25853 25854@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 25855@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{416}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{417} 25856@section GNAT Implementation of Shared Passive Packages 25857 25858 25859@geindex Shared passive packages 25860 25861GNAT fully implements the 25862@geindex pragma Shared_Passive 25863pragma 25864@code{Shared_Passive} for 25865the purpose of designating shared passive packages. 25866This allows the use of passive partitions in the 25867context described in the Ada Reference Manual; i.e., for communication 25868between separate partitions of a distributed application using the 25869features in Annex E. 25870 25871@geindex Annex E 25872 25873@geindex Distribution Systems Annex 25874 25875However, the implementation approach used by GNAT provides for more 25876extensive usage as follows: 25877 25878 25879@table @asis 25880 25881@item @emph{Communication between separate programs} 25882 25883This allows separate programs to access the data in passive 25884partitions, using protected objects for synchronization where 25885needed. The only requirement is that the two programs have a 25886common shared file system. It is even possible for programs 25887running on different machines with different architectures 25888(e.g., different endianness) to communicate via the data in 25889a passive partition. 25890 25891@item @emph{Persistence between program runs} 25892 25893The data in a passive package can persist from one run of a 25894program to another, so that a later program sees the final 25895values stored by a previous run of the same program. 25896@end table 25897 25898The implementation approach used is to store the data in files. A 25899separate stream file is created for each object in the package, and 25900an access to an object causes the corresponding file to be read or 25901written. 25902 25903@geindex SHARED_MEMORY_DIRECTORY environment variable 25904 25905The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 25906set to the directory to be used for these files. 25907The files in this directory 25908have names that correspond to their fully qualified names. For 25909example, if we have the package 25910 25911@example 25912package X is 25913 pragma Shared_Passive (X); 25914 Y : Integer; 25915 Z : Float; 25916end X; 25917@end example 25918 25919and the environment variable is set to @code{/stemp/}, then the files created 25920will have the names: 25921 25922@example 25923/stemp/x.y 25924/stemp/x.z 25925@end example 25926 25927These files are created when a value is initially written to the object, and 25928the files are retained until manually deleted. This provides the persistence 25929semantics. If no file exists, it means that no partition has assigned a value 25930to the variable; in this case the initial value declared in the package 25931will be used. This model ensures that there are no issues in synchronizing 25932the elaboration process, since elaboration of passive packages elaborates the 25933initial values, but does not create the files. 25934 25935The files are written using normal @code{Stream_IO} access. 25936If you want to be able 25937to communicate between programs or partitions running on different 25938architectures, then you should use the XDR versions of the stream attribute 25939routines, since these are architecture independent. 25940 25941If active synchronization is required for access to the variables in the 25942shared passive package, then as described in the Ada Reference Manual, the 25943package may contain protected objects used for this purpose. In this case 25944a lock file (whose name is @code{___lock} (three underscores) 25945is created in the shared memory directory. 25946 25947@geindex ___lock file (for shared passive packages) 25948 25949This is used to provide the required locking 25950semantics for proper protected object synchronization. 25951 25952GNAT supports shared passive packages on all platforms 25953except for OpenVMS. 25954 25955@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 25956@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{418}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{419} 25957@section Code Generation for Array Aggregates 25958 25959 25960Aggregates have a rich syntax and allow the user to specify the values of 25961complex data structures by means of a single construct. As a result, the 25962code generated for aggregates can be quite complex and involve loops, case 25963statements and multiple assignments. In the simplest cases, however, the 25964compiler will recognize aggregates whose components and constraints are 25965fully static, and in those cases the compiler will generate little or no 25966executable code. The following is an outline of the code that GNAT generates 25967for various aggregate constructs. For further details, you will find it 25968useful to examine the output produced by the -gnatG flag to see the expanded 25969source that is input to the code generator. You may also want to examine 25970the assembly code generated at various levels of optimization. 25971 25972The code generated for aggregates depends on the context, the component values, 25973and the type. In the context of an object declaration the code generated is 25974generally simpler than in the case of an assignment. As a general rule, static 25975component values and static subtypes also lead to simpler code. 25976 25977@menu 25978* Static constant aggregates with static bounds:: 25979* Constant aggregates with unconstrained nominal types:: 25980* Aggregates with static bounds:: 25981* Aggregates with nonstatic bounds:: 25982* Aggregates in assignment statements:: 25983 25984@end menu 25985 25986@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 25987@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{41a}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{41b} 25988@subsection Static constant aggregates with static bounds 25989 25990 25991For the declarations: 25992 25993@example 25994type One_Dim is array (1..10) of integer; 25995ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 25996@end example 25997 25998GNAT generates no executable code: the constant ar0 is placed in static memory. 25999The same is true for constant aggregates with named associations: 26000 26001@example 26002Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 26003Cr3 : constant One_Dim := (others => 7777); 26004@end example 26005 26006The same is true for multidimensional constant arrays such as: 26007 26008@example 26009type two_dim is array (1..3, 1..3) of integer; 26010Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 26011@end example 26012 26013The same is true for arrays of one-dimensional arrays: the following are 26014static: 26015 26016@example 26017type ar1b is array (1..3) of boolean; 26018type ar_ar is array (1..3) of ar1b; 26019None : constant ar1b := (others => false); -- fully static 26020None2 : constant ar_ar := (1..3 => None); -- fully static 26021@end example 26022 26023However, for multidimensional aggregates with named associations, GNAT will 26024generate assignments and loops, even if all associations are static. The 26025following two declarations generate a loop for the first dimension, and 26026individual component assignments for the second dimension: 26027 26028@example 26029Zero1: constant two_dim := (1..3 => (1..3 => 0)); 26030Zero2: constant two_dim := (others => (others => 0)); 26031@end example 26032 26033@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 26034@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{41d} 26035@subsection Constant aggregates with unconstrained nominal types 26036 26037 26038In such cases the aggregate itself establishes the subtype, so that 26039associations with @code{others} cannot be used. GNAT determines the 26040bounds for the actual subtype of the aggregate, and allocates the 26041aggregate statically as well. No code is generated for the following: 26042 26043@example 26044type One_Unc is array (natural range <>) of integer; 26045Cr_Unc : constant One_Unc := (12,24,36); 26046@end example 26047 26048@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 26049@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{41f} 26050@subsection Aggregates with static bounds 26051 26052 26053In all previous examples the aggregate was the initial (and immutable) value 26054of a constant. If the aggregate initializes a variable, then code is generated 26055for it as a combination of individual assignments and loops over the target 26056object. The declarations 26057 26058@example 26059Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 26060Cr_Var2 : One_Dim := (others > -1); 26061@end example 26062 26063generate the equivalent of 26064 26065@example 26066Cr_Var1 (1) := 2; 26067Cr_Var1 (2) := 3; 26068Cr_Var1 (3) := 5; 26069Cr_Var1 (4) := 11; 26070 26071for I in Cr_Var2'range loop 26072 Cr_Var2 (I) := -1; 26073end loop; 26074@end example 26075 26076@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 26077@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{421} 26078@subsection Aggregates with nonstatic bounds 26079 26080 26081If the bounds of the aggregate are not statically compatible with the bounds 26082of the nominal subtype of the target, then constraint checks have to be 26083generated on the bounds. For a multidimensional array, constraint checks may 26084have to be applied to sub-arrays individually, if they do not have statically 26085compatible subtypes. 26086 26087@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 26088@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{423} 26089@subsection Aggregates in assignment statements 26090 26091 26092In general, aggregate assignment requires the construction of a temporary, 26093and a copy from the temporary to the target of the assignment. This is because 26094it is not always possible to convert the assignment into a series of individual 26095component assignments. For example, consider the simple case: 26096 26097@example 26098A := (A(2), A(1)); 26099@end example 26100 26101This cannot be converted into: 26102 26103@example 26104A(1) := A(2); 26105A(2) := A(1); 26106@end example 26107 26108So the aggregate has to be built first in a separate location, and then 26109copied into the target. GNAT recognizes simple cases where this intermediate 26110step is not required, and the assignments can be performed in place, directly 26111into the target. The following sufficient criteria are applied: 26112 26113 26114@itemize * 26115 26116@item 26117The bounds of the aggregate are static, and the associations are static. 26118 26119@item 26120The components of the aggregate are static constants, names of 26121simple variables that are not renamings, or expressions not involving 26122indexed components whose operands obey these rules. 26123@end itemize 26124 26125If any of these conditions are violated, the aggregate will be built in 26126a temporary (created either by the front-end or the code generator) and then 26127that temporary will be copied onto the target. 26128 26129@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 26130@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{424}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{425} 26131@section The Size of Discriminated Records with Default Discriminants 26132 26133 26134If a discriminated type @code{T} has discriminants with default values, it is 26135possible to declare an object of this type without providing an explicit 26136constraint: 26137 26138@example 26139type Size is range 1..100; 26140 26141type Rec (D : Size := 15) is record 26142 Name : String (1..D); 26143end T; 26144 26145Word : Rec; 26146@end example 26147 26148Such an object is said to be @emph{unconstrained}. 26149The discriminant of the object 26150can be modified by a full assignment to the object, as long as it preserves the 26151relation between the value of the discriminant, and the value of the components 26152that depend on it: 26153 26154@example 26155Word := (3, "yes"); 26156 26157Word := (5, "maybe"); 26158 26159Word := (5, "no"); -- raises Constraint_Error 26160@end example 26161 26162In order to support this behavior efficiently, an unconstrained object is 26163given the maximum size that any value of the type requires. In the case 26164above, @code{Word} has storage for the discriminant and for 26165a @code{String} of length 100. 26166It is important to note that unconstrained objects do not require dynamic 26167allocation. It would be an improper implementation to place on the heap those 26168components whose size depends on discriminants. (This improper implementation 26169was used by some Ada83 compilers, where the @code{Name} component above 26170would have 26171been stored as a pointer to a dynamic string). Following the principle that 26172dynamic storage management should never be introduced implicitly, 26173an Ada compiler should reserve the full size for an unconstrained declared 26174object, and place it on the stack. 26175 26176This maximum size approach 26177has been a source of surprise to some users, who expect the default 26178values of the discriminants to determine the size reserved for an 26179unconstrained object: "If the default is 15, why should the object occupy 26180a larger size?" 26181The answer, of course, is that the discriminant may be later modified, 26182and its full range of values must be taken into account. This is why the 26183declaration: 26184 26185@example 26186type Rec (D : Positive := 15) is record 26187 Name : String (1..D); 26188end record; 26189 26190Too_Large : Rec; 26191@end example 26192 26193is flagged by the compiler with a warning: 26194an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 26195because the required size includes @code{Positive'Last} 26196bytes. As the first example indicates, the proper approach is to declare an 26197index type of 'reasonable' range so that unconstrained objects are not too 26198large. 26199 26200One final wrinkle: if the object is declared to be @code{aliased}, or if it is 26201created in the heap by means of an allocator, then it is @emph{not} 26202unconstrained: 26203it is constrained by the default values of the discriminants, and those values 26204cannot be modified by full assignment. This is because in the presence of 26205aliasing all views of the object (which may be manipulated by different tasks, 26206say) must be consistent, so it is imperative that the object, once created, 26207remain invariant. 26208 26209@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features 26210@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{426}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{427} 26211@section Strict Conformance to the Ada Reference Manual 26212 26213 26214The dynamic semantics defined by the Ada Reference Manual impose a set of 26215run-time checks to be generated. By default, the GNAT compiler will insert many 26216run-time checks into the compiled code, including most of those required by the 26217Ada Reference Manual. However, there are two checks that are not enabled in 26218the default mode for efficiency reasons: checks for access before elaboration 26219on subprogram calls, and stack overflow checking (most operating systems do not 26220perform this check by default). 26221 26222Strict conformance to the Ada Reference Manual can be achieved by adding two 26223compiler options for dynamic checks for access-before-elaboration on subprogram 26224calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 26225(@emph{-fstack-check}). 26226 26227Note that the result of a floating point arithmetic operation in overflow and 26228invalid situations, when the @code{Machine_Overflows} attribute of the result 26229type is @code{False}, is to generate IEEE NaN and infinite values. This is the 26230case for machines compliant with the IEEE floating-point standard, but on 26231machines that are not fully compliant with this standard, such as Alpha, the 26232@emph{-mieee} compiler flag must be used for achieving IEEE confirming 26233behavior (although at the cost of a significant performance penalty), so 26234infinite and NaN values are properly generated. 26235 26236@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top 26237@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{428}@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{429} 26238@chapter Implementation of Ada 2012 Features 26239 26240 26241@geindex Ada 2012 implementation status 26242 26243@geindex -gnat12 option (gcc) 26244 26245@geindex pragma Ada_2012 26246 26247@geindex configuration pragma Ada_2012 26248 26249@geindex Ada_2012 configuration pragma 26250 26251This chapter contains a complete list of Ada 2012 features that have been 26252implemented. 26253Generally, these features are only 26254available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 26255which is the default behavior, 26256or if the configuration pragma @code{Ada_2012} is used. 26257 26258However, new pragmas, attributes, and restrictions are 26259unconditionally available, since the Ada 95 standard allows the addition of 26260new pragmas, attributes, and restrictions (there are exceptions, which are 26261documented in the individual descriptions), and also certain packages 26262were made available in earlier versions of Ada. 26263 26264An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 26265This date shows the implementation date of the feature. Any wavefront 26266subsequent to this date will contain the indicated feature, as will any 26267subsequent releases. A date of 0000-00-00 means that GNAT has always 26268implemented the feature, or implemented it as soon as it appeared as a 26269binding interpretation. 26270 26271Each feature corresponds to an Ada Issue ('AI') approved by the Ada 26272standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 26273The features are ordered based on the relevant sections of the Ada 26274Reference Manual ("RM"). When a given AI relates to multiple points 26275in the RM, the earliest is used. 26276 26277A complete description of the AIs may be found in 26278@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 26279 26280@geindex AI-0176 (Ada 2012 feature) 26281 26282 26283@itemize * 26284 26285@item 26286@emph{AI-0176 Quantified expressions (2010-09-29)} 26287 26288Both universally and existentially quantified expressions are implemented. 26289They use the new syntax for iterators proposed in AI05-139-2, as well as 26290the standard Ada loop syntax. 26291 26292RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 26293@end itemize 26294 26295@geindex AI-0079 (Ada 2012 feature) 26296 26297 26298@itemize * 26299 26300@item 26301@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 26302 26303Wide characters in the unicode category @emph{other_format} are now allowed in 26304source programs between tokens, but not within a token such as an identifier. 26305 26306RM References: 2.01 (4/2) 2.02 (7) 26307@end itemize 26308 26309@geindex AI-0091 (Ada 2012 feature) 26310 26311 26312@itemize * 26313 26314@item 26315@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 26316 26317Wide characters in the unicode category @emph{other_format} are not permitted 26318within an identifier, since this can be a security problem. The error 26319message for this case has been improved to be more specific, but GNAT has 26320never allowed such characters to appear in identifiers. 26321 26322RM 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) 26323@end itemize 26324 26325@geindex AI-0100 (Ada 2012 feature) 26326 26327 26328@itemize * 26329 26330@item 26331@emph{AI-0100 Placement of pragmas (2010-07-01)} 26332 26333This AI is an earlier version of AI-163. It simplifies the rules 26334for legal placement of pragmas. In the case of lists that allow pragmas, if 26335the list may have no elements, then the list may consist solely of pragmas. 26336 26337RM References: 2.08 (7) 26338@end itemize 26339 26340@geindex AI-0163 (Ada 2012 feature) 26341 26342 26343@itemize * 26344 26345@item 26346@emph{AI-0163 Pragmas in place of null (2010-07-01)} 26347 26348A statement sequence may be composed entirely of pragmas. It is no longer 26349necessary to add a dummy @code{null} statement to make the sequence legal. 26350 26351RM References: 2.08 (7) 2.08 (16) 26352@end itemize 26353 26354@geindex AI-0080 (Ada 2012 feature) 26355 26356 26357@itemize * 26358 26359@item 26360@emph{AI-0080 'View of' not needed if clear from context (0000-00-00)} 26361 26362This is an editorial change only, described as non-testable in the AI. 26363 26364RM References: 3.01 (7) 26365@end itemize 26366 26367@geindex AI-0183 (Ada 2012 feature) 26368 26369 26370@itemize * 26371 26372@item 26373@emph{AI-0183 Aspect specifications (2010-08-16)} 26374 26375Aspect specifications have been fully implemented except for pre and post- 26376conditions, and type invariants, which have their own separate AI's. All 26377forms of declarations listed in the AI are supported. The following is a 26378list of the aspects supported (with GNAT implementation aspects marked) 26379@end itemize 26380 26381 26382@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 26383@headitem 26384 26385Supported Aspect 26386 26387@tab 26388 26389Source 26390 26391@item 26392 26393@code{Ada_2005} 26394 26395@tab 26396 26397-- GNAT 26398 26399@item 26400 26401@code{Ada_2012} 26402 26403@tab 26404 26405-- GNAT 26406 26407@item 26408 26409@code{Address} 26410 26411@tab 26412 26413@item 26414 26415@code{Alignment} 26416 26417@tab 26418 26419@item 26420 26421@code{Atomic} 26422 26423@tab 26424 26425@item 26426 26427@code{Atomic_Components} 26428 26429@tab 26430 26431@item 26432 26433@code{Bit_Order} 26434 26435@tab 26436 26437@item 26438 26439@code{Component_Size} 26440 26441@tab 26442 26443@item 26444 26445@code{Contract_Cases} 26446 26447@tab 26448 26449-- GNAT 26450 26451@item 26452 26453@code{Discard_Names} 26454 26455@tab 26456 26457@item 26458 26459@code{External_Tag} 26460 26461@tab 26462 26463@item 26464 26465@code{Favor_Top_Level} 26466 26467@tab 26468 26469-- GNAT 26470 26471@item 26472 26473@code{Inline} 26474 26475@tab 26476 26477@item 26478 26479@code{Inline_Always} 26480 26481@tab 26482 26483-- GNAT 26484 26485@item 26486 26487@code{Invariant} 26488 26489@tab 26490 26491-- GNAT 26492 26493@item 26494 26495@code{Machine_Radix} 26496 26497@tab 26498 26499@item 26500 26501@code{No_Return} 26502 26503@tab 26504 26505@item 26506 26507@code{Object_Size} 26508 26509@tab 26510 26511-- GNAT 26512 26513@item 26514 26515@code{Pack} 26516 26517@tab 26518 26519@item 26520 26521@code{Persistent_BSS} 26522 26523@tab 26524 26525-- GNAT 26526 26527@item 26528 26529@code{Post} 26530 26531@tab 26532 26533@item 26534 26535@code{Pre} 26536 26537@tab 26538 26539@item 26540 26541@code{Predicate} 26542 26543@tab 26544 26545@item 26546 26547@code{Preelaborable_Initialization} 26548 26549@tab 26550 26551@item 26552 26553@code{Pure_Function} 26554 26555@tab 26556 26557-- GNAT 26558 26559@item 26560 26561@code{Remote_Access_Type} 26562 26563@tab 26564 26565-- GNAT 26566 26567@item 26568 26569@code{Shared} 26570 26571@tab 26572 26573-- GNAT 26574 26575@item 26576 26577@code{Size} 26578 26579@tab 26580 26581@item 26582 26583@code{Storage_Pool} 26584 26585@tab 26586 26587@item 26588 26589@code{Storage_Size} 26590 26591@tab 26592 26593@item 26594 26595@code{Stream_Size} 26596 26597@tab 26598 26599@item 26600 26601@code{Suppress} 26602 26603@tab 26604 26605@item 26606 26607@code{Suppress_Debug_Info} 26608 26609@tab 26610 26611-- GNAT 26612 26613@item 26614 26615@code{Test_Case} 26616 26617@tab 26618 26619-- GNAT 26620 26621@item 26622 26623@code{Thread_Local_Storage} 26624 26625@tab 26626 26627-- GNAT 26628 26629@item 26630 26631@code{Type_Invariant} 26632 26633@tab 26634 26635@item 26636 26637@code{Unchecked_Union} 26638 26639@tab 26640 26641@item 26642 26643@code{Universal_Aliasing} 26644 26645@tab 26646 26647-- GNAT 26648 26649@item 26650 26651@code{Unmodified} 26652 26653@tab 26654 26655-- GNAT 26656 26657@item 26658 26659@code{Unreferenced} 26660 26661@tab 26662 26663-- GNAT 26664 26665@item 26666 26667@code{Unreferenced_Objects} 26668 26669@tab 26670 26671-- GNAT 26672 26673@item 26674 26675@code{Unsuppress} 26676 26677@tab 26678 26679@item 26680 26681@code{Value_Size} 26682 26683@tab 26684 26685-- GNAT 26686 26687@item 26688 26689@code{Volatile} 26690 26691@tab 26692 26693@item 26694 26695@code{Volatile_Components} 26696 26697@tab 26698 26699@item 26700 26701@code{Warnings} 26702 26703@tab 26704 26705-- GNAT 26706 26707@end multitable 26708 26709 26710@quotation 26711 26712Note that for aspects with an expression, e.g. @code{Size}, the expression is 26713treated like a default expression (visibility is analyzed at the point of 26714occurrence of the aspect, but evaluation of the expression occurs at the 26715freeze point of the entity involved). 26716 26717RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 267183.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 26719(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 267209.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2672112.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2672213.03.01 (0) 26723@end quotation 26724 26725@geindex AI-0128 (Ada 2012 feature) 26726 26727 26728@itemize * 26729 26730@item 26731@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 26732 26733If an equality operator ("=") is declared for a type, then the implicitly 26734declared inequality operator ("/=") is a primitive operation of the type. 26735This is the only reasonable interpretation, and is the one always implemented 26736by GNAT, but the RM was not entirely clear in making this point. 26737 26738RM References: 3.02.03 (6) 6.06 (6) 26739@end itemize 26740 26741@geindex AI-0003 (Ada 2012 feature) 26742 26743 26744@itemize * 26745 26746@item 26747@emph{AI-0003 Qualified expressions as names (2010-07-11)} 26748 26749In Ada 2012, a qualified expression is considered to be syntactically a name, 26750meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 26751useful in disambiguating some cases of overloading. 26752 26753RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 267545.04 (7) 26755@end itemize 26756 26757@geindex AI-0120 (Ada 2012 feature) 26758 26759 26760@itemize * 26761 26762@item 26763@emph{AI-0120 Constant instance of protected object (0000-00-00)} 26764 26765This is an RM editorial change only. The section that lists objects that are 26766constant failed to include the current instance of a protected object 26767within a protected function. This has always been treated as a constant 26768in GNAT. 26769 26770RM References: 3.03 (21) 26771@end itemize 26772 26773@geindex AI-0008 (Ada 2012 feature) 26774 26775 26776@itemize * 26777 26778@item 26779@emph{AI-0008 General access to constrained objects (0000-00-00)} 26780 26781The wording in the RM implied that if you have a general access to a 26782constrained object, it could be used to modify the discriminants. This was 26783obviously not intended. @code{Constraint_Error} should be raised, and GNAT 26784has always done so in this situation. 26785 26786RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 26787@end itemize 26788 26789@geindex AI-0093 (Ada 2012 feature) 26790 26791 26792@itemize * 26793 26794@item 26795@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 26796 26797This is an editorial change only, to make more widespread use of the Ada 2012 26798'immutably limited'. 26799 26800RM References: 3.03 (23.4/3) 26801@end itemize 26802 26803@geindex AI-0096 (Ada 2012 feature) 26804 26805 26806@itemize * 26807 26808@item 26809@emph{AI-0096 Deriving from formal private types (2010-07-20)} 26810 26811In general it is illegal for a type derived from a formal limited type to be 26812nonlimited. This AI makes an exception to this rule: derivation is legal 26813if it appears in the private part of the generic, and the formal type is not 26814tagged. If the type is tagged, the legality check must be applied to the 26815private part of the package. 26816 26817RM References: 3.04 (5.1/2) 6.02 (7) 26818@end itemize 26819 26820@geindex AI-0181 (Ada 2012 feature) 26821 26822 26823@itemize * 26824 26825@item 26826@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 26827 26828From Ada 2005 on, soft hyphen is considered a non-graphic character, which 26829means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 26830@code{Image} and @code{Value} attributes for the character types. Strictly 26831speaking this is an inconsistency with Ada 95, but in practice the use of 26832these attributes is so obscure that it will not cause problems. 26833 26834RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 26835@end itemize 26836 26837@geindex AI-0182 (Ada 2012 feature) 26838 26839 26840@itemize * 26841 26842@item 26843@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} 26844 26845This AI allows @code{Character'Value} to accept the string @code{'?'} where 26846@code{?} is any character including non-graphic control characters. GNAT has 26847always accepted such strings. It also allows strings such as 26848@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 26849permission and raises @code{Constraint_Error}, as is certainly still 26850permitted. 26851 26852RM References: 3.05 (56/2) 26853@end itemize 26854 26855@geindex AI-0214 (Ada 2012 feature) 26856 26857 26858@itemize * 26859 26860@item 26861@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 26862 26863Ada 2012 relaxes the restriction that forbids discriminants of tagged types 26864to have default expressions by allowing them when the type is limited. It 26865is often useful to define a default value for a discriminant even though 26866it can't be changed by assignment. 26867 26868RM References: 3.07 (9.1/2) 3.07.02 (3) 26869@end itemize 26870 26871@geindex AI-0102 (Ada 2012 feature) 26872 26873 26874@itemize * 26875 26876@item 26877@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 26878 26879It is illegal to assign an anonymous access constant to an anonymous access 26880variable. The RM did not have a clear rule to prevent this, but GNAT has 26881always generated an error for this usage. 26882 26883RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 26884@end itemize 26885 26886@geindex AI-0158 (Ada 2012 feature) 26887 26888 26889@itemize * 26890 26891@item 26892@emph{AI-0158 Generalizing membership tests (2010-09-16)} 26893 26894This AI extends the syntax of membership tests to simplify complex conditions 26895that can be expressed as membership in a subset of values of any type. It 26896introduces syntax for a list of expressions that may be used in loop contexts 26897as well. 26898 26899RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 26900@end itemize 26901 26902@geindex AI-0173 (Ada 2012 feature) 26903 26904 26905@itemize * 26906 26907@item 26908@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 26909 26910The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 26911with the tag of an abstract type, and @code{False} otherwise. 26912 26913RM References: 3.09 (7.4/2) 3.09 (12.4/2) 26914@end itemize 26915 26916@geindex AI-0076 (Ada 2012 feature) 26917 26918 26919@itemize * 26920 26921@item 26922@emph{AI-0076 function with controlling result (0000-00-00)} 26923 26924This is an editorial change only. The RM defines calls with controlling 26925results, but uses the term 'function with controlling result' without an 26926explicit definition. 26927 26928RM References: 3.09.02 (2/2) 26929@end itemize 26930 26931@geindex AI-0126 (Ada 2012 feature) 26932 26933 26934@itemize * 26935 26936@item 26937@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 26938 26939This AI clarifies dispatching rules, and simply confirms that dispatching 26940executes the operation of the parent type when there is no explicitly or 26941implicitly declared operation for the descendant type. This has always been 26942the case in all versions of GNAT. 26943 26944RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 26945@end itemize 26946 26947@geindex AI-0097 (Ada 2012 feature) 26948 26949 26950@itemize * 26951 26952@item 26953@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 26954 26955The RM as written implied that in some cases it was possible to create an 26956object of an abstract type, by having an abstract extension inherit a non- 26957abstract constructor from its parent type. This mistake has been corrected 26958in GNAT and in the RM, and this construct is now illegal. 26959 26960RM References: 3.09.03 (4/2) 26961@end itemize 26962 26963@geindex AI-0203 (Ada 2012 feature) 26964 26965 26966@itemize * 26967 26968@item 26969@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 26970 26971A return_subtype_indication cannot denote an abstract subtype. GNAT has never 26972permitted such usage. 26973 26974RM References: 3.09.03 (8/3) 26975@end itemize 26976 26977@geindex AI-0198 (Ada 2012 feature) 26978 26979 26980@itemize * 26981 26982@item 26983@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 26984 26985This AI resolves a conflict between two rules involving inherited abstract 26986operations and predefined operators. If a derived numeric type inherits 26987an abstract operator, it overrides the predefined one. This interpretation 26988was always the one implemented in GNAT. 26989 26990RM References: 3.09.03 (4/3) 26991@end itemize 26992 26993@geindex AI-0073 (Ada 2012 feature) 26994 26995 26996@itemize * 26997 26998@item 26999@emph{AI-0073 Functions returning abstract types (2010-07-10)} 27000 27001This AI covers a number of issues regarding returning abstract types. In 27002particular generic functions cannot have abstract result types or access 27003result types designated an abstract type. There are some other cases which 27004are detailed in the AI. Note that this binding interpretation has not been 27005retrofitted to operate before Ada 2012 mode, since it caused a significant 27006number of regressions. 27007 27008RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 27009@end itemize 27010 27011@geindex AI-0070 (Ada 2012 feature) 27012 27013 27014@itemize * 27015 27016@item 27017@emph{AI-0070 Elaboration of interface types (0000-00-00)} 27018 27019This is an editorial change only, there are no testable consequences short of 27020checking for the absence of generated code for an interface declaration. 27021 27022RM References: 3.09.04 (18/2) 27023@end itemize 27024 27025@geindex AI-0208 (Ada 2012 feature) 27026 27027 27028@itemize * 27029 27030@item 27031@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 27032 27033The wording in the Ada 2005 RM concerning characteristics of incomplete views 27034was incorrect and implied that some programs intended to be legal were now 27035illegal. GNAT had never considered such programs illegal, so it has always 27036implemented the intent of this AI. 27037 27038RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 27039@end itemize 27040 27041@geindex AI-0162 (Ada 2012 feature) 27042 27043 27044@itemize * 27045 27046@item 27047@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 27048 27049Incomplete types are made more useful by allowing them to be completed by 27050private types and private extensions. 27051 27052RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 27053@end itemize 27054 27055@geindex AI-0098 (Ada 2012 feature) 27056 27057 27058@itemize * 27059 27060@item 27061@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 27062 27063An unintentional omission in the RM implied some inconsistent restrictions on 27064the use of anonymous access to subprogram values. These restrictions were not 27065intentional, and have never been enforced by GNAT. 27066 27067RM References: 3.10.01 (6) 3.10.01 (9.2/2) 27068@end itemize 27069 27070@geindex AI-0199 (Ada 2012 feature) 27071 27072 27073@itemize * 27074 27075@item 27076@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 27077 27078A choice list in a record aggregate can include several components of 27079(distinct) anonymous access types as long as they have matching designated 27080subtypes. 27081 27082RM References: 4.03.01 (16) 27083@end itemize 27084 27085@geindex AI-0220 (Ada 2012 feature) 27086 27087 27088@itemize * 27089 27090@item 27091@emph{AI-0220 Needed components for aggregates (0000-00-00)} 27092 27093This AI addresses a wording problem in the RM that appears to permit some 27094complex cases of aggregates with nonstatic discriminants. GNAT has always 27095implemented the intended semantics. 27096 27097RM References: 4.03.01 (17) 27098@end itemize 27099 27100@geindex AI-0147 (Ada 2012 feature) 27101 27102 27103@itemize * 27104 27105@item 27106@emph{AI-0147 Conditional expressions (2009-03-29)} 27107 27108Conditional expressions are permitted. The form of such an expression is: 27109 27110@example 27111(if expr then expr @{elsif expr then expr@} [else expr]) 27112@end example 27113 27114The parentheses can be omitted in contexts where parentheses are present 27115anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 27116clause is omitted, @strong{else} @emph{True} is assumed; 27117thus @code{(if A then B)} is a way to conveniently represent 27118@emph{(A implies B)} in standard logic. 27119 27120RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 271214.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 27122@end itemize 27123 27124@geindex AI-0037 (Ada 2012 feature) 27125 27126 27127@itemize * 27128 27129@item 27130@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 27131 27132This AI confirms that an association of the form @code{Indx => <>} in an 27133array aggregate must raise @code{Constraint_Error} if @code{Indx} 27134is out of range. The RM specified a range check on other associations, but 27135not when the value of the association was defaulted. GNAT has always inserted 27136a constraint check on the index value. 27137 27138RM References: 4.03.03 (29) 27139@end itemize 27140 27141@geindex AI-0123 (Ada 2012 feature) 27142 27143 27144@itemize * 27145 27146@item 27147@emph{AI-0123 Composability of equality (2010-04-13)} 27148 27149Equality of untagged record composes, so that the predefined equality for a 27150composite type that includes a component of some untagged record type 27151@code{R} uses the equality operation of @code{R} (which may be user-defined 27152or predefined). This makes the behavior of untagged records identical to that 27153of tagged types in this respect. 27154 27155This change is an incompatibility with previous versions of Ada, but it 27156corrects a non-uniformity that was often a source of confusion. Analysis of 27157a large number of industrial programs indicates that in those rare cases 27158where a composite type had an untagged record component with a user-defined 27159equality, either there was no use of the composite equality, or else the code 27160expected the same composability as for tagged types, and thus had a bug that 27161would be fixed by this change. 27162 27163RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 271648.05.04 (8) 27165@end itemize 27166 27167@geindex AI-0088 (Ada 2012 feature) 27168 27169 27170@itemize * 27171 27172@item 27173@emph{AI-0088 The value of exponentiation (0000-00-00)} 27174 27175This AI clarifies the equivalence rule given for the dynamic semantics of 27176exponentiation: the value of the operation can be obtained by repeated 27177multiplication, but the operation can be implemented otherwise (for example 27178using the familiar divide-by-two-and-square algorithm, even if this is less 27179accurate), and does not imply repeated reads of a volatile base. 27180 27181RM References: 4.05.06 (11) 27182@end itemize 27183 27184@geindex AI-0188 (Ada 2012 feature) 27185 27186 27187@itemize * 27188 27189@item 27190@emph{AI-0188 Case expressions (2010-01-09)} 27191 27192Case expressions are permitted. This allows use of constructs such as: 27193 27194@example 27195X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 27196@end example 27197 27198RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 27199@end itemize 27200 27201@geindex AI-0104 (Ada 2012 feature) 27202 27203 27204@itemize * 27205 27206@item 27207@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 27208 27209The assignment @code{Ptr := new not null Some_Ptr;} will raise 27210@code{Constraint_Error} because the default value of the allocated object is 27211@strong{null}. This useless construct is illegal in Ada 2012. 27212 27213RM References: 4.08 (2) 27214@end itemize 27215 27216@geindex AI-0157 (Ada 2012 feature) 27217 27218 27219@itemize * 27220 27221@item 27222@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 27223 27224Allocation and Deallocation from an empty storage pool (i.e. allocation or 27225deallocation of a pointer for which a static storage size clause of zero 27226has been given) is now illegal and is detected as such. GNAT 27227previously gave a warning but not an error. 27228 27229RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 27230@end itemize 27231 27232@geindex AI-0179 (Ada 2012 feature) 27233 27234 27235@itemize * 27236 27237@item 27238@emph{AI-0179 Statement not required after label (2010-04-10)} 27239 27240It is not necessary to have a statement following a label, so a label 27241can appear at the end of a statement sequence without the need for putting a 27242null statement afterwards, but it is not allowable to have only labels and 27243no real statements in a statement sequence. 27244 27245RM References: 5.01 (2) 27246@end itemize 27247 27248@geindex AI-0139-2 (Ada 2012 feature) 27249 27250 27251@itemize * 27252 27253@item 27254@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 27255 27256The new syntax for iterating over arrays and containers is now implemented. 27257Iteration over containers is for now limited to read-only iterators. Only 27258default iterators are supported, with the syntax: @code{for Elem of C}. 27259 27260RM References: 5.05 27261@end itemize 27262 27263@geindex AI-0134 (Ada 2012 feature) 27264 27265 27266@itemize * 27267 27268@item 27269@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 27270 27271For full conformance, the profiles of anonymous-access-to-subprogram 27272parameters must match. GNAT has always enforced this rule. 27273 27274RM References: 6.03.01 (18) 27275@end itemize 27276 27277@geindex AI-0207 (Ada 2012 feature) 27278 27279 27280@itemize * 27281 27282@item 27283@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 27284 27285This AI confirms that access_to_constant indication must match for mode 27286conformance. This was implemented in GNAT when the qualifier was originally 27287introduced in Ada 2005. 27288 27289RM References: 6.03.01 (16/2) 27290@end itemize 27291 27292@geindex AI-0046 (Ada 2012 feature) 27293 27294 27295@itemize * 27296 27297@item 27298@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 27299 27300For full conformance, in the case of access parameters, the null exclusion 27301must match (either both or neither must have @code{not null}). 27302 27303RM References: 6.03.02 (18) 27304@end itemize 27305 27306@geindex AI-0118 (Ada 2012 feature) 27307 27308 27309@itemize * 27310 27311@item 27312@emph{AI-0118 The association of parameter associations (0000-00-00)} 27313 27314This AI clarifies the rules for named associations in subprogram calls and 27315generic instantiations. The rules have been in place since Ada 83. 27316 27317RM References: 6.04.01 (2) 12.03 (9) 27318@end itemize 27319 27320@geindex AI-0196 (Ada 2012 feature) 27321 27322 27323@itemize * 27324 27325@item 27326@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 27327 27328Null exclusion checks are not made for @code{out} parameters when 27329evaluating the actual parameters. GNAT has never generated these checks. 27330 27331RM References: 6.04.01 (13) 27332@end itemize 27333 27334@geindex AI-0015 (Ada 2012 feature) 27335 27336 27337@itemize * 27338 27339@item 27340@emph{AI-0015 Constant return objects (0000-00-00)} 27341 27342The return object declared in an @emph{extended_return_statement} may be 27343declared constant. This was always intended, and GNAT has always allowed it. 27344 27345RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 273466.05 (5.7/2) 27347@end itemize 27348 27349@geindex AI-0032 (Ada 2012 feature) 27350 27351 27352@itemize * 27353 27354@item 27355@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 27356 27357If a function returns a class-wide type, the object of an extended return 27358statement can be declared with a specific type that is covered by the class- 27359wide type. This has been implemented in GNAT since the introduction of 27360extended returns. Note AI-0103 complements this AI by imposing matching 27361rules for constrained return types. 27362 27363RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 273646.05 (8/2) 27365@end itemize 27366 27367@geindex AI-0103 (Ada 2012 feature) 27368 27369 27370@itemize * 27371 27372@item 27373@emph{AI-0103 Static matching for extended return (2010-07-23)} 27374 27375If the return subtype of a function is an elementary type or a constrained 27376type, the subtype indication in an extended return statement must match 27377statically this return subtype. 27378 27379RM References: 6.05 (5.2/2) 27380@end itemize 27381 27382@geindex AI-0058 (Ada 2012 feature) 27383 27384 27385@itemize * 27386 27387@item 27388@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 27389 27390The RM had some incorrect wording implying wrong treatment of abnormal 27391completion in an extended return. GNAT has always implemented the intended 27392correct semantics as described by this AI. 27393 27394RM References: 6.05 (22/2) 27395@end itemize 27396 27397@geindex AI-0050 (Ada 2012 feature) 27398 27399 27400@itemize * 27401 27402@item 27403@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 27404 27405The implementation permissions for raising @code{Constraint_Error} early on a function call 27406when it was clear an exception would be raised were over-permissive and allowed 27407mishandling of discriminants in some cases. GNAT did 27408not take advantage of these incorrect permissions in any case. 27409 27410RM References: 6.05 (24/2) 27411@end itemize 27412 27413@geindex AI-0125 (Ada 2012 feature) 27414 27415 27416@itemize * 27417 27418@item 27419@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 27420 27421In Ada 2012, the declaration of a primitive operation of a type extension 27422or private extension can also override an inherited primitive that is not 27423visible at the point of this declaration. 27424 27425RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 27426@end itemize 27427 27428@geindex AI-0062 (Ada 2012 feature) 27429 27430 27431@itemize * 27432 27433@item 27434@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 27435 27436A full constant may have a null exclusion even if its associated deferred 27437constant does not. GNAT has always allowed this. 27438 27439RM References: 7.04 (6/2) 7.04 (7.1/2) 27440@end itemize 27441 27442@geindex AI-0178 (Ada 2012 feature) 27443 27444 27445@itemize * 27446 27447@item 27448@emph{AI-0178 Incomplete views are limited (0000-00-00)} 27449 27450This AI clarifies the role of incomplete views and plugs an omission in the 27451RM. GNAT always correctly restricted the use of incomplete views and types. 27452 27453RM References: 7.05 (3/2) 7.05 (6/2) 27454@end itemize 27455 27456@geindex AI-0087 (Ada 2012 feature) 27457 27458 27459@itemize * 27460 27461@item 27462@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 27463 27464The actual for a formal nonlimited derived type cannot be limited. In 27465particular, a formal derived type that extends a limited interface but which 27466is not explicitly limited cannot be instantiated with a limited type. 27467 27468RM References: 7.05 (5/2) 12.05.01 (5.1/2) 27469@end itemize 27470 27471@geindex AI-0099 (Ada 2012 feature) 27472 27473 27474@itemize * 27475 27476@item 27477@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 27478 27479This AI clarifies that 'needs finalization' is part of dynamic semantics, 27480and therefore depends on the run-time characteristics of an object (i.e. its 27481tag) and not on its nominal type. As the AI indicates: "we do not expect 27482this to affect any implementation'@w{'}. 27483 27484RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 27485@end itemize 27486 27487@geindex AI-0064 (Ada 2012 feature) 27488 27489 27490@itemize * 27491 27492@item 27493@emph{AI-0064 Redundant finalization rule (0000-00-00)} 27494 27495This is an editorial change only. The intended behavior is already checked 27496by an existing ACATS test, which GNAT has always executed correctly. 27497 27498RM References: 7.06.01 (17.1/1) 27499@end itemize 27500 27501@geindex AI-0026 (Ada 2012 feature) 27502 27503 27504@itemize * 27505 27506@item 27507@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 27508 27509Record representation clauses concerning Unchecked_Union types cannot mention 27510the discriminant of the type. The type of a component declared in the variant 27511part of an Unchecked_Union cannot be controlled, have controlled components, 27512nor have protected or task parts. If an Unchecked_Union type is declared 27513within the body of a generic unit or its descendants, then the type of a 27514component declared in the variant part cannot be a formal private type or a 27515formal private extension declared within the same generic unit. 27516 27517RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 27518@end itemize 27519 27520@geindex AI-0205 (Ada 2012 feature) 27521 27522 27523@itemize * 27524 27525@item 27526@emph{AI-0205 Extended return declares visible name (0000-00-00)} 27527 27528This AI corrects a simple omission in the RM. Return objects have always 27529been visible within an extended return statement. 27530 27531RM References: 8.03 (17) 27532@end itemize 27533 27534@geindex AI-0042 (Ada 2012 feature) 27535 27536 27537@itemize * 27538 27539@item 27540@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 27541 27542This AI fixes a wording gap in the RM. An operation of a synchronized 27543interface can be implemented by a protected or task entry, but the abstract 27544operation is not being overridden in the usual sense, and it must be stated 27545separately that this implementation is legal. This has always been the case 27546in GNAT. 27547 27548RM References: 9.01 (9.2/2) 9.04 (11.1/2) 27549@end itemize 27550 27551@geindex AI-0030 (Ada 2012 feature) 27552 27553 27554@itemize * 27555 27556@item 27557@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 27558 27559Requeue is permitted to a protected, synchronized or task interface primitive 27560providing it is known that the overriding operation is an entry. Otherwise 27561the requeue statement has the same effect as a procedure call. Use of pragma 27562@code{Implemented} provides a way to impose a static requirement on the 27563overriding operation by adhering to one of the implementation kinds: entry, 27564protected procedure or any of the above. 27565 27566RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 275679.05.04 (6) 9.05.04 (7) 9.05.04 (12) 27568@end itemize 27569 27570@geindex AI-0201 (Ada 2012 feature) 27571 27572 27573@itemize * 27574 27575@item 27576@emph{AI-0201 Independence of atomic object components (2010-07-22)} 27577 27578If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 27579attribute, then individual components may not be addressable by independent 27580tasks. However, if the representation clause has no effect (is confirming), 27581then independence is not compromised. Furthermore, in GNAT, specification of 27582other appropriately addressable component sizes (e.g. 16 for 8-bit 27583characters) also preserves independence. GNAT now gives very clear warnings 27584both for the declaration of such a type, and for any assignment to its components. 27585 27586RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 27587@end itemize 27588 27589@geindex AI-0009 (Ada 2012 feature) 27590 27591 27592@itemize * 27593 27594@item 27595@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 27596 27597This AI introduces the new pragmas @code{Independent} and 27598@code{Independent_Components}, 27599which control guaranteeing independence of access to objects and components. 27600The AI also requires independence not unaffected by confirming rep clauses. 27601 27602RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 27603C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 27604@end itemize 27605 27606@geindex AI-0072 (Ada 2012 feature) 27607 27608 27609@itemize * 27610 27611@item 27612@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 27613 27614This AI clarifies that task signalling for reading @code{'Terminated} only 27615occurs if the result is True. GNAT semantics has always been consistent with 27616this notion of task signalling. 27617 27618RM References: 9.10 (6.1/1) 27619@end itemize 27620 27621@geindex AI-0108 (Ada 2012 feature) 27622 27623 27624@itemize * 27625 27626@item 27627@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 27628 27629This AI confirms that an incomplete type from a limited view does not have 27630discriminants. This has always been the case in GNAT. 27631 27632RM References: 10.01.01 (12.3/2) 27633@end itemize 27634 27635@geindex AI-0129 (Ada 2012 feature) 27636 27637 27638@itemize * 27639 27640@item 27641@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 27642 27643This AI clarifies the description of limited views: a limited view of a 27644package includes only one view of a type that has an incomplete declaration 27645and a full declaration (there is no possible ambiguity in a client package). 27646This AI also fixes an omission: a nested package in the private part has no 27647limited view. GNAT always implemented this correctly. 27648 27649RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 27650@end itemize 27651 27652@geindex AI-0077 (Ada 2012 feature) 27653 27654 27655@itemize * 27656 27657@item 27658@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 27659 27660This AI clarifies that a declaration does not include a context clause, 27661and confirms that it is illegal to have a context in which both a limited 27662and a nonlimited view of a package are accessible. Such double visibility 27663was always rejected by GNAT. 27664 27665RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 27666@end itemize 27667 27668@geindex AI-0122 (Ada 2012 feature) 27669 27670 27671@itemize * 27672 27673@item 27674@emph{AI-0122 Private with and children of generics (0000-00-00)} 27675 27676This AI clarifies the visibility of private children of generic units within 27677instantiations of a parent. GNAT has always handled this correctly. 27678 27679RM References: 10.01.02 (12/2) 27680@end itemize 27681 27682@geindex AI-0040 (Ada 2012 feature) 27683 27684 27685@itemize * 27686 27687@item 27688@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 27689 27690This AI confirms that a limited with clause in a child unit cannot name 27691an ancestor of the unit. This has always been checked in GNAT. 27692 27693RM References: 10.01.02 (20/2) 27694@end itemize 27695 27696@geindex AI-0132 (Ada 2012 feature) 27697 27698 27699@itemize * 27700 27701@item 27702@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 27703 27704This AI fills a gap in the description of library unit pragmas. The pragma 27705clearly must apply to a library unit, even if it does not carry the name 27706of the enclosing unit. GNAT has always enforced the required check. 27707 27708RM References: 10.01.05 (7) 27709@end itemize 27710 27711@geindex AI-0034 (Ada 2012 feature) 27712 27713 27714@itemize * 27715 27716@item 27717@emph{AI-0034 Categorization of limited views (0000-00-00)} 27718 27719The RM makes certain limited with clauses illegal because of categorization 27720considerations, when the corresponding normal with would be legal. This is 27721not intended, and GNAT has always implemented the recommended behavior. 27722 27723RM References: 10.02.01 (11/1) 10.02.01 (17/2) 27724@end itemize 27725 27726@geindex AI-0035 (Ada 2012 feature) 27727 27728 27729@itemize * 27730 27731@item 27732@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 27733 27734This AI remedies some inconsistencies in the legality rules for Pure units. 27735Derived access types are legal in a pure unit (on the assumption that the 27736rule for a zero storage pool size has been enforced on the ancestor type). 27737The rules are enforced in generic instances and in subunits. GNAT has always 27738implemented the recommended behavior. 27739 27740RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 27741@end itemize 27742 27743@geindex AI-0219 (Ada 2012 feature) 27744 27745 27746@itemize * 27747 27748@item 27749@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 27750 27751This AI refines the rules for the cases with limited parameters which do not 27752allow the implementations to omit 'redundant'. GNAT now properly conforms 27753to the requirements of this binding interpretation. 27754 27755RM References: 10.02.01 (18/2) 27756@end itemize 27757 27758@geindex AI-0043 (Ada 2012 feature) 27759 27760 27761@itemize * 27762 27763@item 27764@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 27765 27766This AI covers various omissions in the RM regarding the raising of 27767exceptions. GNAT has always implemented the intended semantics. 27768 27769RM References: 11.04.01 (10.1/2) 11 (2) 27770@end itemize 27771 27772@geindex AI-0200 (Ada 2012 feature) 27773 27774 27775@itemize * 27776 27777@item 27778@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 27779 27780This AI plugs a gap in the RM which appeared to allow some obviously intended 27781illegal instantiations. GNAT has never allowed these instantiations. 27782 27783RM References: 12.07 (16) 27784@end itemize 27785 27786@geindex AI-0112 (Ada 2012 feature) 27787 27788 27789@itemize * 27790 27791@item 27792@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 27793 27794This AI concerns giving names to various representation aspects, but the 27795practical effect is simply to make the use of duplicate 27796@code{Atomic[_Components]}, 27797@code{Volatile[_Components]}, and 27798@code{Independent[_Components]} pragmas illegal, and GNAT 27799now performs this required check. 27800 27801RM References: 13.01 (8) 27802@end itemize 27803 27804@geindex AI-0106 (Ada 2012 feature) 27805 27806 27807@itemize * 27808 27809@item 27810@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 27811 27812The RM appeared to allow representation pragmas on generic formal parameters, 27813but this was not intended, and GNAT has never permitted this usage. 27814 27815RM References: 13.01 (9.1/1) 27816@end itemize 27817 27818@geindex AI-0012 (Ada 2012 feature) 27819 27820 27821@itemize * 27822 27823@item 27824@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 27825 27826It is now illegal to give an inappropriate component size or a pragma 27827@code{Pack} that attempts to change the component size in the case of atomic 27828or aliased components. Previously GNAT ignored such an attempt with a 27829warning. 27830 27831RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 27832@end itemize 27833 27834@geindex AI-0039 (Ada 2012 feature) 27835 27836 27837@itemize * 27838 27839@item 27840@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 27841 27842The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 27843for stream attributes, but these were never useful and are now illegal. GNAT 27844has always regarded such expressions as illegal. 27845 27846RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 27847@end itemize 27848 27849@geindex AI-0095 (Ada 2012 feature) 27850 27851 27852@itemize * 27853 27854@item 27855@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 27856 27857The prefix of @code{'Address} cannot statically denote a subprogram with 27858convention @code{Intrinsic}. The use of the @code{Address} attribute raises 27859@code{Program_Error} if the prefix denotes a subprogram with convention 27860@code{Intrinsic}. 27861 27862RM References: 13.03 (11/1) 27863@end itemize 27864 27865@geindex AI-0116 (Ada 2012 feature) 27866 27867 27868@itemize * 27869 27870@item 27871@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 27872 27873This AI requires that the alignment of a class-wide object be no greater 27874than the alignment of any type in the class. GNAT has always followed this 27875recommendation. 27876 27877RM References: 13.03 (29) 13.11 (16) 27878@end itemize 27879 27880@geindex AI-0146 (Ada 2012 feature) 27881 27882 27883@itemize * 27884 27885@item 27886@emph{AI-0146 Type invariants (2009-09-21)} 27887 27888Type invariants may be specified for private types using the aspect notation. 27889Aspect @code{Type_Invariant} may be specified for any private type, 27890@code{Type_Invariant'Class} can 27891only be specified for tagged types, and is inherited by any descendent of the 27892tagged types. The invariant is a boolean expression that is tested for being 27893true in the following situations: conversions to the private type, object 27894declarations for the private type that are default initialized, and 27895[@strong{in}] @strong{out} 27896parameters and returned result on return from any primitive operation for 27897the type that is visible to a client. 27898GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 27899@code{Invariant'Class} for @code{Type_Invariant'Class}. 27900 27901RM References: 13.03.03 (00) 27902@end itemize 27903 27904@geindex AI-0078 (Ada 2012 feature) 27905 27906 27907@itemize * 27908 27909@item 27910@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 27911 27912In Ada 2012, compilers are required to support unchecked conversion where the 27913target alignment is a multiple of the source alignment. GNAT always supported 27914this case (and indeed all cases of differing alignments, doing copies where 27915required if the alignment was reduced). 27916 27917RM References: 13.09 (7) 27918@end itemize 27919 27920@geindex AI-0195 (Ada 2012 feature) 27921 27922 27923@itemize * 27924 27925@item 27926@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 27927 27928The handling of invalid values is now designated to be implementation 27929defined. This is a documentation change only, requiring Annex M in the GNAT 27930Reference Manual to document this handling. 27931In GNAT, checks for invalid values are made 27932only when necessary to avoid erroneous behavior. Operations like assignments 27933which cannot cause erroneous behavior ignore the possibility of invalid 27934values and do not do a check. The date given above applies only to the 27935documentation change, this behavior has always been implemented by GNAT. 27936 27937RM References: 13.09.01 (10) 27938@end itemize 27939 27940@geindex AI-0193 (Ada 2012 feature) 27941 27942 27943@itemize * 27944 27945@item 27946@emph{AI-0193 Alignment of allocators (2010-09-16)} 27947 27948This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 27949analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 27950of size. 27951 27952RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2795313.11.01 (2) 13.11.01 (3) 27954@end itemize 27955 27956@geindex AI-0177 (Ada 2012 feature) 27957 27958 27959@itemize * 27960 27961@item 27962@emph{AI-0177 Parameterized expressions (2010-07-10)} 27963 27964The new Ada 2012 notion of parameterized expressions is implemented. The form 27965is: 27966 27967@example 27968function-specification is (expression) 27969@end example 27970 27971This is exactly equivalent to the 27972corresponding function body that returns the expression, but it can appear 27973in a package spec. Note that the expression must be parenthesized. 27974 27975RM References: 13.11.01 (3/2) 27976@end itemize 27977 27978@geindex AI-0033 (Ada 2012 feature) 27979 27980 27981@itemize * 27982 27983@item 27984@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 27985 27986Neither of these two pragmas may appear within a generic template, because 27987the generic might be instantiated at other than the library level. 27988 27989RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 27990@end itemize 27991 27992@geindex AI-0161 (Ada 2012 feature) 27993 27994 27995@itemize * 27996 27997@item 27998@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 27999 28000A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 28001of the default stream attributes for elementary types. If this restriction is 28002in force, then it is necessary to provide explicit subprograms for any 28003stream attributes used. 28004 28005RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 28006@end itemize 28007 28008@geindex AI-0194 (Ada 2012 feature) 28009 28010 28011@itemize * 28012 28013@item 28014@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 28015 28016The @code{Stream_Size} attribute returns the default number of bits in the 28017stream representation of the given type. 28018This value is not affected by the presence 28019of stream subprogram attributes for the type. GNAT has always implemented 28020this interpretation. 28021 28022RM References: 13.13.02 (1.2/2) 28023@end itemize 28024 28025@geindex AI-0109 (Ada 2012 feature) 28026 28027 28028@itemize * 28029 28030@item 28031@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 28032 28033This AI is an editorial change only. It removes the need for a tag check 28034that can never fail. 28035 28036RM References: 13.13.02 (34/2) 28037@end itemize 28038 28039@geindex AI-0007 (Ada 2012 feature) 28040 28041 28042@itemize * 28043 28044@item 28045@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 28046 28047The RM as written appeared to limit the possibilities of declaring read 28048attribute procedures for private scalar types. This limitation was not 28049intended, and has never been enforced by GNAT. 28050 28051RM References: 13.13.02 (50/2) 13.13.02 (51/2) 28052@end itemize 28053 28054@geindex AI-0065 (Ada 2012 feature) 28055 28056 28057@itemize * 28058 28059@item 28060@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 28061 28062This AI clarifies the fact that all remote access types support external 28063streaming. This fixes an obvious oversight in the definition of the 28064language, and GNAT always implemented the intended correct rules. 28065 28066RM References: 13.13.02 (52/2) 28067@end itemize 28068 28069@geindex AI-0019 (Ada 2012 feature) 28070 28071 28072@itemize * 28073 28074@item 28075@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 28076 28077The RM suggests that primitive subprograms of a specific tagged type are 28078frozen when the tagged type is frozen. This would be an incompatible change 28079and is not intended. GNAT has never attempted this kind of freezing and its 28080behavior is consistent with the recommendation of this AI. 28081 28082RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 28083@end itemize 28084 28085@geindex AI-0017 (Ada 2012 feature) 28086 28087 28088@itemize * 28089 28090@item 28091@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 28092 28093So-called 'Taft-amendment types' (i.e., types that are completed in package 28094bodies) are not frozen by the occurrence of bodies in the 28095enclosing declarative part. GNAT always implemented this properly. 28096 28097RM References: 13.14 (3/1) 28098@end itemize 28099 28100@geindex AI-0060 (Ada 2012 feature) 28101 28102 28103@itemize * 28104 28105@item 28106@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 28107 28108This AI extends the definition of remote access types to include access 28109to limited, synchronized, protected or task class-wide interface types. 28110GNAT already implemented this extension. 28111 28112RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 28113@end itemize 28114 28115@geindex AI-0114 (Ada 2012 feature) 28116 28117 28118@itemize * 28119 28120@item 28121@emph{AI-0114 Classification of letters (0000-00-00)} 28122 28123The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 28124181 (@code{MICRO SIGN}), and 28125186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 28126lower case letters by Unicode. 28127However, they are not allowed in identifiers, and they 28128return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 28129This behavior is consistent with that defined in Ada 95. 28130 28131RM References: A.03.02 (59) A.04.06 (7) 28132@end itemize 28133 28134@geindex AI-0185 (Ada 2012 feature) 28135 28136 28137@itemize * 28138 28139@item 28140@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 28141 28142Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 28143classification functions for @code{Wide_Character} and 28144@code{Wide_Wide_Character}, as well as providing 28145case folding routines for @code{Wide_[Wide_]Character} and 28146@code{Wide_[Wide_]String}. 28147 28148RM References: A.03.05 (0) A.03.06 (0) 28149@end itemize 28150 28151@geindex AI-0031 (Ada 2012 feature) 28152 28153 28154@itemize * 28155 28156@item 28157@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 28158 28159A new version of @code{Find_Token} is added to all relevant string packages, 28160with an extra parameter @code{From}. Instead of starting at the first 28161character of the string, the search for a matching Token starts at the 28162character indexed by the value of @code{From}. 28163These procedures are available in all versions of Ada 28164but if used in versions earlier than Ada 2012 they will generate a warning 28165that an Ada 2012 subprogram is being used. 28166 28167RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 28168A.04.05 (46) 28169@end itemize 28170 28171@geindex AI-0056 (Ada 2012 feature) 28172 28173 28174@itemize * 28175 28176@item 28177@emph{AI-0056 Index on null string returns zero (0000-00-00)} 28178 28179The wording in the Ada 2005 RM implied an incompatible handling of the 28180@code{Index} functions, resulting in raising an exception instead of 28181returning zero in some situations. 28182This was not intended and has been corrected. 28183GNAT always returned zero, and is thus consistent with this AI. 28184 28185RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 28186@end itemize 28187 28188@geindex AI-0137 (Ada 2012 feature) 28189 28190 28191@itemize * 28192 28193@item 28194@emph{AI-0137 String encoding package (2010-03-25)} 28195 28196The packages @code{Ada.Strings.UTF_Encoding}, together with its child 28197packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 28198and @code{Wide_Wide_Strings} have been 28199implemented. These packages (whose documentation can be found in the spec 28200files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 28201@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 28202@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 28203values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 28204UTF-16), as well as conversions between the different UTF encodings. With 28205the exception of @code{Wide_Wide_Strings}, these packages are available in 28206Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 28207The @code{Wide_Wide_Strings} package 28208is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 28209mode since it uses @code{Wide_Wide_Character}). 28210 28211RM References: A.04.11 28212@end itemize 28213 28214@geindex AI-0038 (Ada 2012 feature) 28215 28216 28217@itemize * 28218 28219@item 28220@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 28221 28222These are minor errors in the description on three points. The intent on 28223all these points has always been clear, and GNAT has always implemented the 28224correct intended semantics. 28225 28226RM 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) 28227@end itemize 28228 28229@geindex AI-0044 (Ada 2012 feature) 28230 28231 28232@itemize * 28233 28234@item 28235@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 28236 28237This AI places restrictions on allowed instantiations of generic containers. 28238These restrictions are not checked by the compiler, so there is nothing to 28239change in the implementation. This affects only the RM documentation. 28240 28241RM 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) 28242@end itemize 28243 28244@geindex AI-0127 (Ada 2012 feature) 28245 28246 28247@itemize * 28248 28249@item 28250@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 28251 28252This package provides an interface for identifying the current locale. 28253 28254RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 28255A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 28256@end itemize 28257 28258@geindex AI-0002 (Ada 2012 feature) 28259 28260 28261@itemize * 28262 28263@item 28264@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 28265 28266The compiler is not required to support exporting an Ada subprogram with 28267convention C if there are parameters or a return type of an unconstrained 28268array type (such as @code{String}). GNAT allows such declarations but 28269generates warnings. It is possible, but complicated, to write the 28270corresponding C code and certainly such code would be specific to GNAT and 28271non-portable. 28272 28273RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 28274@end itemize 28275 28276@geindex AI05-0216 (Ada 2012 feature) 28277 28278 28279@itemize * 28280 28281@item 28282@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 28283 28284It is clearly the intention that @code{No_Task_Hierarchy} is intended to 28285forbid tasks declared locally within subprograms, or functions returning task 28286objects, and that is the implementation that GNAT has always provided. 28287However the language in the RM was not sufficiently clear on this point. 28288Thus this is a documentation change in the RM only. 28289 28290RM References: D.07 (3/3) 28291@end itemize 28292 28293@geindex AI-0211 (Ada 2012 feature) 28294 28295 28296@itemize * 28297 28298@item 28299@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 28300 28301The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 28302@code{Ada.Real_Time.Timing_Events.Set_Handler}. 28303 28304RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 28305@end itemize 28306 28307@geindex AI-0190 (Ada 2012 feature) 28308 28309 28310@itemize * 28311 28312@item 28313@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 28314 28315This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 28316used to control storage pools globally. 28317In particular, you can force every access 28318type that is used for allocation (@strong{new}) to have an explicit storage pool, 28319or you can declare a pool globally to be used for all access types that lack 28320an explicit one. 28321 28322RM References: D.07 (8) 28323@end itemize 28324 28325@geindex AI-0189 (Ada 2012 feature) 28326 28327 28328@itemize * 28329 28330@item 28331@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 28332 28333This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 28334which says that no dynamic allocation will occur once elaboration is 28335completed. 28336In general this requires a run-time check, which is not required, and which 28337GNAT does not attempt. But the static cases of allocators in a task body or 28338in the body of the main program are detected and flagged at compile or bind 28339time. 28340 28341RM References: D.07 (19.1/2) H.04 (23.3/2) 28342@end itemize 28343 28344@geindex AI-0171 (Ada 2012 feature) 28345 28346 28347@itemize * 28348 28349@item 28350@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 28351 28352A new package @code{System.Multiprocessors} is added, together with the 28353definition of pragma @code{CPU} for controlling task affinity. A new no 28354dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 28355is added to the Ravenscar profile. 28356 28357RM References: D.13.01 (4/2) D.16 28358@end itemize 28359 28360@geindex AI-0210 (Ada 2012 feature) 28361 28362 28363@itemize * 28364 28365@item 28366@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 28367 28368This is a documentation only issue regarding wording of metric requirements, 28369that does not affect the implementation of the compiler. 28370 28371RM References: D.15 (24/2) 28372@end itemize 28373 28374@geindex AI-0206 (Ada 2012 feature) 28375 28376 28377@itemize * 28378 28379@item 28380@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 28381 28382Remote types packages are now allowed to depend on preelaborated packages. 28383This was formerly considered illegal. 28384 28385RM References: E.02.02 (6) 28386@end itemize 28387 28388@geindex AI-0152 (Ada 2012 feature) 28389 28390 28391@itemize * 28392 28393@item 28394@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 28395 28396Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 28397where the type of the returned value is an anonymous access type. 28398 28399RM References: H.04 (8/1) 28400@end itemize 28401 28402@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top 28403@anchor{gnat_rm/obsolescent_features id1}@anchor{42a}@anchor{gnat_rm/obsolescent_features doc}@anchor{42b}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15} 28404@chapter Obsolescent Features 28405 28406 28407This chapter describes features that are provided by GNAT, but are 28408considered obsolescent since there are preferred ways of achieving 28409the same effect. These features are provided solely for historical 28410compatibility purposes. 28411 28412@menu 28413* pragma No_Run_Time:: 28414* pragma Ravenscar:: 28415* pragma Restricted_Run_Time:: 28416* pragma Task_Info:: 28417* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 28418 28419@end menu 28420 28421@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 28422@anchor{gnat_rm/obsolescent_features id2}@anchor{42c}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{42d} 28423@section pragma No_Run_Time 28424 28425 28426The pragma @code{No_Run_Time} is used to achieve an affect similar 28427to the use of the "Zero Foot Print" configurable run time, but without 28428requiring a specially configured run time. The result of using this 28429pragma, which must be used for all units in a partition, is to restrict 28430the use of any language features requiring run-time support code. The 28431preferred usage is to use an appropriately configured run-time that 28432includes just those features that are to be made accessible. 28433 28434@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 28435@anchor{gnat_rm/obsolescent_features id3}@anchor{42e}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{42f} 28436@section pragma Ravenscar 28437 28438 28439The pragma @code{Ravenscar} has exactly the same effect as pragma 28440@code{Profile (Ravenscar)}. The latter usage is preferred since it 28441is part of the new Ada 2005 standard. 28442 28443@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 28444@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{430}@anchor{gnat_rm/obsolescent_features id4}@anchor{431} 28445@section pragma Restricted_Run_Time 28446 28447 28448The pragma @code{Restricted_Run_Time} has exactly the same effect as 28449pragma @code{Profile (Restricted)}. The latter usage is 28450preferred since the Ada 2005 pragma @code{Profile} is intended for 28451this kind of implementation dependent addition. 28452 28453@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 28454@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{432}@anchor{gnat_rm/obsolescent_features id5}@anchor{433} 28455@section pragma Task_Info 28456 28457 28458The functionality provided by pragma @code{Task_Info} is now part of the 28459Ada language. The @code{CPU} aspect and the package 28460@code{System.Multiprocessors} offer a less system-dependent way to specify 28461task affinity or to query the number of processsors. 28462 28463Syntax 28464 28465@example 28466pragma Task_Info (EXPRESSION); 28467@end example 28468 28469This pragma appears within a task definition (like pragma 28470@code{Priority}) and applies to the task in which it appears. The 28471argument must be of type @code{System.Task_Info.Task_Info_Type}. 28472The @code{Task_Info} pragma provides system dependent control over 28473aspects of tasking implementation, for example, the ability to map 28474tasks to specific processors. For details on the facilities available 28475for the version of GNAT that you are using, see the documentation 28476in the spec of package System.Task_Info in the runtime 28477library. 28478 28479@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 28480@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{434}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{435} 28481@section package System.Task_Info (@code{s-tasinf.ads}) 28482 28483 28484This package provides target dependent functionality that is used 28485to support the @code{Task_Info} pragma. The predefined Ada package 28486@code{System.Multiprocessors} and the @code{CPU} aspect now provide a 28487standard replacement for GNAT's @code{Task_Info} functionality. 28488 28489@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 28490@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{436}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{437} 28491@chapter Compatibility and Porting Guide 28492 28493 28494This chapter presents some guidelines for developing portable Ada code, 28495describes the compatibility issues that may arise between 28496GNAT and other Ada compilation systems (including those for Ada 83), 28497and shows how GNAT can expedite porting 28498applications developed in other Ada environments. 28499 28500@menu 28501* Writing Portable Fixed-Point Declarations:: 28502* Compatibility with Ada 83:: 28503* Compatibility between Ada 95 and Ada 2005:: 28504* Implementation-dependent characteristics:: 28505* Compatibility with Other Ada Systems:: 28506* Representation Clauses:: 28507* Compatibility with HP Ada 83:: 28508 28509@end menu 28510 28511@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 28512@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{438}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{439} 28513@section Writing Portable Fixed-Point Declarations 28514 28515 28516The Ada Reference Manual gives an implementation freedom to choose bounds 28517that are narrower by @code{Small} from the given bounds. 28518For example, if we write 28519 28520@example 28521type F1 is delta 1.0 range -128.0 .. +128.0; 28522@end example 28523 28524then the implementation is allowed to choose -128.0 .. +127.0 if it 28525likes, but is not required to do so. 28526 28527This leads to possible portability problems, so let's have a closer 28528look at this, and figure out how to avoid these problems. 28529 28530First, why does this freedom exist, and why would an implementation 28531take advantage of it? To answer this, take a closer look at the type 28532declaration for @code{F1} above. If the compiler uses the given bounds, 28533it would need 9 bits to hold the largest positive value (and typically 28534that means 16 bits on all machines). But if the implementation chooses 28535the +127.0 bound then it can fit values of the type in 8 bits. 28536 28537Why not make the user write +127.0 if that's what is wanted? 28538The rationale is that if you are thinking of fixed point 28539as a kind of 'poor man's floating-point', then you don't want 28540to be thinking about the scaled integers that are used in its 28541representation. Let's take another example: 28542 28543@example 28544type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 28545@end example 28546 28547Looking at this declaration, it seems casually as though 28548it should fit in 16 bits, but again that extra positive value 28549+1.0 has the scaled integer equivalent of 2**15 which is one too 28550big for signed 16 bits. The implementation can treat this as: 28551 28552@example 28553type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 28554@end example 28555 28556and the Ada language design team felt that this was too annoying 28557to require. We don't need to debate this decision at this point, 28558since it is well established (the rule about narrowing the ranges 28559dates to Ada 83). 28560 28561But the important point is that an implementation is not required 28562to do this narrowing, so we have a potential portability problem. 28563We could imagine three types of implementation: 28564 28565 28566@enumerate a 28567 28568@item 28569those that narrow the range automatically if they can figure 28570out that the narrower range will allow storage in a smaller machine unit, 28571 28572@item 28573those that will narrow only if forced to by a @code{'Size} clause, and 28574 28575@item 28576those that will never narrow. 28577@end enumerate 28578 28579Now if we are language theoreticians, we can imagine a fourth 28580approach: to narrow all the time, e.g. to treat 28581 28582@example 28583type F3 is delta 1.0 range -10.0 .. +23.0; 28584@end example 28585 28586as though it had been written: 28587 28588@example 28589type F3 is delta 1.0 range -9.0 .. +22.0; 28590@end example 28591 28592But although technically allowed, such a behavior would be hostile and silly, 28593and no real compiler would do this. All real compilers will fall into one of 28594the categories (a), (b) or (c) above. 28595 28596So, how do you get the compiler to do what you want? The answer is give the 28597actual bounds you want, and then use a @code{'Small} clause and a 28598@code{'Size} clause to absolutely pin down what the compiler does. 28599E.g., for @code{F2} above, we will write: 28600 28601@example 28602My_Small : constant := 2.0**(-15); 28603My_First : constant := -1.0; 28604My_Last : constant := +1.0 - My_Small; 28605 28606type F2 is delta My_Small range My_First .. My_Last; 28607@end example 28608 28609and then add 28610 28611@example 28612for F2'Small use my_Small; 28613for F2'Size use 16; 28614@end example 28615 28616In practice all compilers will do the same thing here and will give you 28617what you want, so the above declarations are fully portable. If you really 28618want to play language lawyer and guard against ludicrous behavior by the 28619compiler you could add 28620 28621@example 28622Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 28623Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 28624@end example 28625 28626One or other or both are allowed to be illegal if the compiler is 28627behaving in a silly manner, but at least the silly compiler will not 28628get away with silently messing with your (very clear) intentions. 28629 28630If you follow this scheme you will be guaranteed that your fixed-point 28631types will be portable. 28632 28633@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 28634@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{43a}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{43b} 28635@section Compatibility with Ada 83 28636 28637 28638@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 28639 28640Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 28641are highly upwards compatible with Ada 83. In 28642particular, the design intention was that the difficulties associated 28643with moving from Ada 83 to later versions of the standard should be no greater 28644than those that occur when moving from one Ada 83 system to another. 28645 28646However, there are a number of points at which there are minor 28647incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 28648full details of these issues as they relate to Ada 95, 28649and should be consulted for a complete treatment. 28650In practice the 28651following subsections treat the most likely issues to be encountered. 28652 28653@menu 28654* Legal Ada 83 programs that are illegal in Ada 95:: 28655* More deterministic semantics:: 28656* Changed semantics:: 28657* Other language compatibility issues:: 28658 28659@end menu 28660 28661@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 28662@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{43c}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{43d} 28663@subsection Legal Ada 83 programs that are illegal in Ada 95 28664 28665 28666Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 28667Ada 95 and later versions of the standard: 28668 28669 28670@itemize * 28671 28672@item 28673@emph{Character literals} 28674 28675Some uses of character literals are ambiguous. Since Ada 95 has introduced 28676@code{Wide_Character} as a new predefined character type, some uses of 28677character literals that were legal in Ada 83 are illegal in Ada 95. 28678For example: 28679 28680@example 28681for Char in 'A' .. 'Z' loop ... end loop; 28682@end example 28683 28684The problem is that 'A' and 'Z' could be from either 28685@code{Character} or @code{Wide_Character}. The simplest correction 28686is to make the type explicit; e.g.: 28687 28688@example 28689for Char in Character range 'A' .. 'Z' loop ... end loop; 28690@end example 28691 28692@item 28693@emph{New reserved words} 28694 28695The identifiers @code{abstract}, @code{aliased}, @code{protected}, 28696@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. 28697Existing Ada 83 code using any of these identifiers must be edited to 28698use some alternative name. 28699 28700@item 28701@emph{Freezing rules} 28702 28703The rules in Ada 95 are slightly different with regard to the point at 28704which entities are frozen, and representation pragmas and clauses are 28705not permitted past the freeze point. This shows up most typically in 28706the form of an error message complaining that a representation item 28707appears too late, and the appropriate corrective action is to move 28708the item nearer to the declaration of the entity to which it refers. 28709 28710A particular case is that representation pragmas 28711cannot be applied to a subprogram body. If necessary, a separate subprogram 28712declaration must be introduced to which the pragma can be applied. 28713 28714@item 28715@emph{Optional bodies for library packages} 28716 28717In Ada 83, a package that did not require a package body was nevertheless 28718allowed to have one. This lead to certain surprises in compiling large 28719systems (situations in which the body could be unexpectedly ignored by the 28720binder). In Ada 95, if a package does not require a body then it is not 28721permitted to have a body. To fix this problem, simply remove a redundant 28722body if it is empty, or, if it is non-empty, introduce a dummy declaration 28723into the spec that makes the body required. One approach is to add a private 28724part to the package declaration (if necessary), and define a parameterless 28725procedure called @code{Requires_Body}, which must then be given a dummy 28726procedure body in the package body, which then becomes required. 28727Another approach (assuming that this does not introduce elaboration 28728circularities) is to add an @code{Elaborate_Body} pragma to the package spec, 28729since one effect of this pragma is to require the presence of a package body. 28730 28731@item 28732@emph{Numeric_Error is the same exception as Constraint_Error} 28733 28734In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. 28735This means that it is illegal to have separate exception handlers for 28736the two exceptions. The fix is simply to remove the handler for the 28737@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 28738@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). 28739 28740@item 28741@emph{Indefinite subtypes in generics} 28742 28743In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) 28744as the actual for a generic formal private type, but then the instantiation 28745would be illegal if there were any instances of declarations of variables 28746of this type in the generic body. In Ada 95, to avoid this clear violation 28747of the methodological principle known as the 'contract model', 28748the generic declaration explicitly indicates whether 28749or not such instantiations are permitted. If a generic formal parameter 28750has explicit unknown discriminants, indicated by using @code{(<>)} after the 28751subtype name, then it can be instantiated with indefinite types, but no 28752stand-alone variables can be declared of this type. Any attempt to declare 28753such a variable will result in an illegality at the time the generic is 28754declared. If the @code{(<>)} notation is not used, then it is illegal 28755to instantiate the generic with an indefinite type. 28756This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 28757It will show up as a compile time error, and 28758the fix is usually simply to add the @code{(<>)} to the generic declaration. 28759@end itemize 28760 28761@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 28762@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{43e}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{43f} 28763@subsection More deterministic semantics 28764 28765 28766 28767@itemize * 28768 28769@item 28770@emph{Conversions} 28771 28772Conversions from real types to integer types round away from 0. In Ada 83 28773the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 28774implementation freedom was intended to support unbiased rounding in 28775statistical applications, but in practice it interfered with portability. 28776In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 28777is required. Numeric code may be affected by this change in semantics. 28778Note, though, that this issue is no worse than already existed in Ada 83 28779when porting code from one vendor to another. 28780 28781@item 28782@emph{Tasking} 28783 28784The Real-Time Annex introduces a set of policies that define the behavior of 28785features that were implementation dependent in Ada 83, such as the order in 28786which open select branches are executed. 28787@end itemize 28788 28789@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 28790@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{440}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{441} 28791@subsection Changed semantics 28792 28793 28794The worst kind of incompatibility is one where a program that is legal in 28795Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 28796possible in Ada 83. Fortunately this is extremely rare, but the one 28797situation that you should be alert to is the change in the predefined type 28798@code{Character} from 7-bit ASCII to 8-bit Latin-1. 28799 28800@quotation 28801 28802@geindex Latin-1 28803@end quotation 28804 28805 28806@itemize * 28807 28808@item 28809@emph{Range of type `@w{`}Character`@w{`}} 28810 28811The range of @code{Standard.Character} is now the full 256 characters 28812of Latin-1, whereas in most Ada 83 implementations it was restricted 28813to 128 characters. Although some of the effects of 28814this change will be manifest in compile-time rejection of legal 28815Ada 83 programs it is possible for a working Ada 83 program to have 28816a different effect in Ada 95, one that was not permitted in Ada 83. 28817As an example, the expression 28818@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now 28819delivers @code{255} as its value. 28820In general, you should look at the logic of any 28821character-processing Ada 83 program and see whether it needs to be adapted 28822to work correctly with Latin-1. Note that the predefined Ada 95 API has a 28823character handling package that may be relevant if code needs to be adapted 28824to account for the additional Latin-1 elements. 28825The desirable fix is to 28826modify the program to accommodate the full character set, but in some cases 28827it may be convenient to define a subtype or derived type of Character that 28828covers only the restricted range. 28829@end itemize 28830 28831@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 28832@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{442}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{443} 28833@subsection Other language compatibility issues 28834 28835 28836 28837@itemize * 28838 28839@item 28840@emph{-gnat83} switch 28841 28842All implementations of GNAT provide a switch that causes GNAT to operate 28843in Ada 83 mode. In this mode, some but not all compatibility problems 28844of the type described above are handled automatically. For example, the 28845new reserved words introduced in Ada 95 and Ada 2005 are treated simply 28846as identifiers as in Ada 83. However, 28847in practice, it is usually advisable to make the necessary modifications 28848to the program to remove the need for using this switch. 28849See the @code{Compiling Different Versions of Ada} section in 28850the @cite{GNAT User's Guide}. 28851 28852@item 28853Support for removed Ada 83 pragmas and attributes 28854 28855A number of pragmas and attributes from Ada 83 were removed from Ada 95, 28856generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 28857compilers are allowed, but not required, to implement these missing 28858elements. In contrast with some other compilers, GNAT implements all 28859such pragmas and attributes, eliminating this compatibility concern. These 28860include @code{pragma Interface} and the floating point type attributes 28861(@code{Emax}, @code{Mantissa}, etc.), among other items. 28862@end itemize 28863 28864@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 28865@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{445} 28866@section Compatibility between Ada 95 and Ada 2005 28867 28868 28869@geindex Compatibility between Ada 95 and Ada 2005 28870 28871Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 28872a number of incompatibilities. Several are enumerated below; 28873for a complete description please see the 28874@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 28875@cite{Rationale for Ada 2005}. 28876 28877 28878@itemize * 28879 28880@item 28881@emph{New reserved words.} 28882 28883The words @code{interface}, @code{overriding} and @code{synchronized} are 28884reserved in Ada 2005. 28885A pre-Ada 2005 program that uses any of these as an identifier will be 28886illegal. 28887 28888@item 28889@emph{New declarations in predefined packages.} 28890 28891A number of packages in the predefined environment contain new declarations: 28892@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, 28893@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, 28894@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, 28895@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, 28896@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. 28897If an Ada 95 program does a @code{with} and @code{use} of any of these 28898packages, the new declarations may cause name clashes. 28899 28900@item 28901@emph{Access parameters.} 28902 28903A nondispatching subprogram with an access parameter cannot be renamed 28904as a dispatching operation. This was permitted in Ada 95. 28905 28906@item 28907@emph{Access types, discriminants, and constraints.} 28908 28909Rule changes in this area have led to some incompatibilities; for example, 28910constrained subtypes of some access types are not permitted in Ada 2005. 28911 28912@item 28913@emph{Aggregates for limited types.} 28914 28915The allowance of aggregates for limited types in Ada 2005 raises the 28916possibility of ambiguities in legal Ada 95 programs, since additional types 28917now need to be considered in expression resolution. 28918 28919@item 28920@emph{Fixed-point multiplication and division.} 28921 28922Certain expressions involving '*' or '/' for a fixed-point type, which 28923were legal in Ada 95 and invoked the predefined versions of these operations, 28924are now ambiguous. 28925The ambiguity may be resolved either by applying a type conversion to the 28926expression, or by explicitly invoking the operation from package 28927@code{Standard}. 28928 28929@item 28930@emph{Return-by-reference types.} 28931 28932The Ada 95 return-by-reference mechanism has been removed. Instead, the user 28933can declare a function returning a value from an anonymous access type. 28934@end itemize 28935 28936@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 28937@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{447} 28938@section Implementation-dependent characteristics 28939 28940 28941Although the Ada language defines the semantics of each construct as 28942precisely as practical, in some situations (for example for reasons of 28943efficiency, or where the effect is heavily dependent on the host or target 28944platform) the implementation is allowed some freedom. In porting Ada 83 28945code to GNAT, you need to be aware of whether / how the existing code 28946exercised such implementation dependencies. Such characteristics fall into 28947several categories, and GNAT offers specific support in assisting the 28948transition from certain Ada 83 compilers. 28949 28950@menu 28951* Implementation-defined pragmas:: 28952* Implementation-defined attributes:: 28953* Libraries:: 28954* Elaboration order:: 28955* Target-specific aspects:: 28956 28957@end menu 28958 28959@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 28960@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{449} 28961@subsection Implementation-defined pragmas 28962 28963 28964Ada compilers are allowed to supplement the language-defined pragmas, and 28965these are a potential source of non-portability. All GNAT-defined pragmas 28966are described in @ref{7,,Implementation Defined Pragmas}, 28967and these include several that are specifically 28968intended to correspond to other vendors' Ada 83 pragmas. 28969For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. 28970For compatibility with HP Ada 83, GNAT supplies the pragmas 28971@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, 28972@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, 28973and @code{Volatile}. 28974Other relevant pragmas include @code{External} and @code{Link_With}. 28975Some vendor-specific 28976Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are 28977recognized, thus 28978avoiding compiler rejection of units that contain such pragmas; they are not 28979relevant in a GNAT context and hence are not otherwise implemented. 28980 28981@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 28982@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{44b} 28983@subsection Implementation-defined attributes 28984 28985 28986Analogous to pragmas, the set of attributes may be extended by an 28987implementation. All GNAT-defined attributes are described in 28988@ref{8,,Implementation Defined Attributes}, 28989and these include several that are specifically intended 28990to correspond to other vendors' Ada 83 attributes. For migrating from VADS, 28991the attribute @code{VADS_Size} may be useful. For compatibility with HP 28992Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and 28993@code{Type_Class}. 28994 28995@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 28996@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{44d} 28997@subsection Libraries 28998 28999 29000Vendors may supply libraries to supplement the standard Ada API. If Ada 83 29001code uses vendor-specific libraries then there are several ways to manage 29002this in Ada 95 and later versions of the standard: 29003 29004 29005@itemize * 29006 29007@item 29008If the source code for the libraries (specs and bodies) are 29009available, then the libraries can be migrated in the same way as the 29010application. 29011 29012@item 29013If the source code for the specs but not the bodies are 29014available, then you can reimplement the bodies. 29015 29016@item 29017Some features introduced by Ada 95 obviate the need for library support. For 29018example most Ada 83 vendors supplied a package for unsigned integers. The 29019Ada 95 modular type feature is the preferred way to handle this need, so 29020instead of migrating or reimplementing the unsigned integer package it may 29021be preferable to retrofit the application using modular types. 29022@end itemize 29023 29024@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 29025@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{44f} 29026@subsection Elaboration order 29027 29028 29029The implementation can choose any elaboration order consistent with the unit 29030dependency relationship. This freedom means that some orders can result in 29031Program_Error being raised due to an 'Access Before Elaboration': an attempt 29032to invoke a subprogram before its body has been elaborated, or to instantiate 29033a generic before the generic body has been elaborated. By default GNAT 29034attempts to choose a safe order (one that will not encounter access before 29035elaboration problems) by implicitly inserting @code{Elaborate} or 29036@code{Elaborate_All} pragmas where 29037needed. However, this can lead to the creation of elaboration circularities 29038and a resulting rejection of the program by gnatbind. This issue is 29039thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix 29040in the @cite{GNAT User's Guide}. 29041In brief, there are several 29042ways to deal with this situation: 29043 29044 29045@itemize * 29046 29047@item 29048Modify the program to eliminate the circularities, e.g., by moving 29049elaboration-time code into explicitly-invoked procedures 29050 29051@item 29052Constrain the elaboration order by including explicit @code{Elaborate_Body} or 29053@code{Elaborate} pragmas, and then inhibit the generation of implicit 29054@code{Elaborate_All} 29055pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 29056(by selectively suppressing elaboration checks via pragma 29057@code{Suppress(Elaboration_Check)} when it is safe to do so). 29058@end itemize 29059 29060@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 29061@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{451} 29062@subsection Target-specific aspects 29063 29064 29065Low-level applications need to deal with machine addresses, data 29066representations, interfacing with assembler code, and similar issues. If 29067such an Ada 83 application is being ported to different target hardware (for 29068example where the byte endianness has changed) then you will need to 29069carefully examine the program logic; the porting effort will heavily depend 29070on the robustness of the original design. Moreover, Ada 95 (and thus 29071Ada 2005 and Ada 2012) are sometimes 29072incompatible with typical Ada 83 compiler practices regarding implicit 29073packing, the meaning of the Size attribute, and the size of access values. 29074GNAT's approach to these issues is described in @ref{452,,Representation Clauses}. 29075 29076@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 29077@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{453}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{454} 29078@section Compatibility with Other Ada Systems 29079 29080 29081If programs avoid the use of implementation dependent and 29082implementation defined features, as documented in the 29083@cite{Ada Reference Manual}, there should be a high degree of portability between 29084GNAT and other Ada systems. The following are specific items which 29085have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 29086compilers, but do not affect porting code to GNAT. 29087(As of January 2007, GNAT is the only compiler available for Ada 2005; 29088the following issues may or may not arise for Ada 2005 programs 29089when other compilers appear.) 29090 29091 29092@itemize * 29093 29094@item 29095@emph{Ada 83 Pragmas and Attributes} 29096 29097Ada 95 compilers are allowed, but not required, to implement the missing 29098Ada 83 pragmas and attributes that are no longer defined in Ada 95. 29099GNAT implements all such pragmas and attributes, eliminating this as 29100a compatibility concern, but some other Ada 95 compilers reject these 29101pragmas and attributes. 29102 29103@item 29104@emph{Specialized Needs Annexes} 29105 29106GNAT implements the full set of special needs annexes. At the 29107current time, it is the only Ada 95 compiler to do so. This means that 29108programs making use of these features may not be portable to other Ada 2910995 compilation systems. 29110 29111@item 29112@emph{Representation Clauses} 29113 29114Some other Ada 95 compilers implement only the minimal set of 29115representation clauses required by the Ada 95 reference manual. GNAT goes 29116far beyond this minimal set, as described in the next section. 29117@end itemize 29118 29119@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 29120@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{455} 29121@section Representation Clauses 29122 29123 29124The Ada 83 reference manual was quite vague in describing both the minimal 29125required implementation of representation clauses, and also their precise 29126effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 29127minimal set of capabilities required is still quite limited. 29128 29129GNAT implements the full required set of capabilities in 29130Ada 95 and Ada 2005, but also goes much further, and in particular 29131an effort has been made to be compatible with existing Ada 83 usage to the 29132greatest extent possible. 29133 29134A few cases exist in which Ada 83 compiler behavior is incompatible with 29135the requirements in Ada 95 (and thus also Ada 2005). These are instances of 29136intentional or accidental dependence on specific implementation dependent 29137characteristics of these Ada 83 compilers. The following is a list of 29138the cases most likely to arise in existing Ada 83 code. 29139 29140 29141@itemize * 29142 29143@item 29144@emph{Implicit Packing} 29145 29146Some Ada 83 compilers allowed a Size specification to cause implicit 29147packing of an array or record. This could cause expensive implicit 29148conversions for change of representation in the presence of derived 29149types, and the Ada design intends to avoid this possibility. 29150Subsequent AI's were issued to make it clear that such implicit 29151change of representation in response to a Size clause is inadvisable, 29152and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 29153Reference Manuals as implementation advice that is followed by GNAT. 29154The problem will show up as an error 29155message rejecting the size clause. The fix is simply to provide 29156the explicit pragma @code{Pack}, or for more fine tuned control, provide 29157a Component_Size clause. 29158 29159@item 29160@emph{Meaning of Size Attribute} 29161 29162The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 29163the minimal number of bits required to hold values of the type. For example, 29164on a 32-bit machine, the size of @code{Natural} will typically be 31 and not 2916532 (since no sign bit is required). Some Ada 83 compilers gave 31, and 29166some 32 in this situation. This problem will usually show up as a compile 29167time error, but not always. It is a good idea to check all uses of the 29168'Size attribute when porting Ada 83 code. The GNAT specific attribute 29169Object_Size can provide a useful way of duplicating the behavior of 29170some Ada 83 compiler systems. 29171 29172@item 29173@emph{Size of Access Types} 29174 29175A common assumption in Ada 83 code is that an access type is in fact a pointer, 29176and that therefore it will be the same size as a System.Address value. This 29177assumption is true for GNAT in most cases with one exception. For the case of 29178a pointer to an unconstrained array type (where the bounds may vary from one 29179value of the access type to another), the default is to use a 'fat pointer', 29180which is represented as two separate pointers, one to the bounds, and one to 29181the array. This representation has a number of advantages, including improved 29182efficiency. However, it may cause some difficulties in porting existing Ada 83 29183code which makes the assumption that, for example, pointers fit in 32 bits on 29184a machine with 32-bit addressing. 29185 29186To get around this problem, GNAT also permits the use of 'thin pointers' for 29187access types in this case (where the designated type is an unconstrained array 29188type). These thin pointers are indeed the same size as a System.Address value. 29189To specify a thin pointer, use a size clause for the type, for example: 29190 29191@example 29192type X is access all String; 29193for X'Size use Standard'Address_Size; 29194@end example 29195 29196which will cause the type X to be represented using a single pointer. 29197When using this representation, the bounds are right behind the array. 29198This representation is slightly less efficient, and does not allow quite 29199such flexibility in the use of foreign pointers or in using the 29200Unrestricted_Access attribute to create pointers to non-aliased objects. 29201But for any standard portable use of the access type it will work in 29202a functionally correct manner and allow porting of existing code. 29203Note that another way of forcing a thin pointer representation 29204is to use a component size clause for the element size in an array, 29205or a record representation clause for an access field in a record. 29206 29207See the documentation of Unrestricted_Access in the GNAT RM for a 29208full discussion of possible problems using this attribute in conjunction 29209with thin pointers. 29210@end itemize 29211 29212@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 29213@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{457} 29214@section Compatibility with HP Ada 83 29215 29216 29217All the HP Ada 83 pragmas and attributes are recognized, although only a subset 29218of them can sensibly be implemented. The description of pragmas in 29219@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 29220applicable to GNAT. 29221 29222 29223@itemize * 29224 29225@item 29226@emph{Default floating-point representation} 29227 29228In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 29229it is VMS format. 29230 29231@item 29232@emph{System} 29233 29234the package System in GNAT exactly corresponds to the definition in the 29235Ada 95 reference manual, which means that it excludes many of the 29236HP Ada 83 extensions. However, a separate package Aux_DEC is provided 29237that contains the additional definitions, and a special pragma, 29238Extend_System allows this package to be treated transparently as an 29239extension of package System. 29240@end itemize 29241 29242@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 29243@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{458}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{459} 29244@chapter GNU Free Documentation License 29245 29246 29247Version 1.3, 3 November 2008 29248 29249Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 29250@indicateurl{http://fsf.org/} 29251 29252Everyone is permitted to copy and distribute verbatim copies of this 29253license document, but changing it is not allowed. 29254 29255@strong{Preamble} 29256 29257The purpose of this License is to make a manual, textbook, or other 29258functional and useful document "free" in the sense of freedom: to 29259assure everyone the effective freedom to copy and redistribute it, 29260with or without modifying it, either commercially or noncommercially. 29261Secondarily, this License preserves for the author and publisher a way 29262to get credit for their work, while not being considered responsible 29263for modifications made by others. 29264 29265This License is a kind of "copyleft", which means that derivative 29266works of the document must themselves be free in the same sense. It 29267complements the GNU General Public License, which is a copyleft 29268license designed for free software. 29269 29270We have designed this License in order to use it for manuals for free 29271software, because free software needs free documentation: a free 29272program should come with manuals providing the same freedoms that the 29273software does. But this License is not limited to software manuals; 29274it can be used for any textual work, regardless of subject matter or 29275whether it is published as a printed book. We recommend this License 29276principally for works whose purpose is instruction or reference. 29277 29278@strong{1. APPLICABILITY AND DEFINITIONS} 29279 29280This License applies to any manual or other work, in any medium, that 29281contains a notice placed by the copyright holder saying it can be 29282distributed under the terms of this License. Such a notice grants a 29283world-wide, royalty-free license, unlimited in duration, to use that 29284work under the conditions stated herein. The @strong{Document}, below, 29285refers to any such manual or work. Any member of the public is a 29286licensee, and is addressed as "@strong{you}". You accept the license if you 29287copy, modify or distribute the work in a way requiring permission 29288under copyright law. 29289 29290A "@strong{Modified Version}" of the Document means any work containing the 29291Document or a portion of it, either copied verbatim, or with 29292modifications and/or translated into another language. 29293 29294A "@strong{Secondary Section}" is a named appendix or a front-matter section of 29295the Document that deals exclusively with the relationship of the 29296publishers or authors of the Document to the Document's overall subject 29297(or to related matters) and contains nothing that could fall directly 29298within that overall subject. (Thus, if the Document is in part a 29299textbook of mathematics, a Secondary Section may not explain any 29300mathematics.) The relationship could be a matter of historical 29301connection with the subject or with related matters, or of legal, 29302commercial, philosophical, ethical or political position regarding 29303them. 29304 29305The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 29306are designated, as being those of Invariant Sections, in the notice 29307that says that the Document is released under this License. If a 29308section does not fit the above definition of Secondary then it is not 29309allowed to be designated as Invariant. The Document may contain zero 29310Invariant Sections. If the Document does not identify any Invariant 29311Sections then there are none. 29312 29313The "@strong{Cover Texts}" are certain short passages of text that are listed, 29314as Front-Cover Texts or Back-Cover Texts, in the notice that says that 29315the Document is released under this License. A Front-Cover Text may 29316be at most 5 words, and a Back-Cover Text may be at most 25 words. 29317 29318A "@strong{Transparent}" copy of the Document means a machine-readable copy, 29319represented in a format whose specification is available to the 29320general public, that is suitable for revising the document 29321straightforwardly with generic text editors or (for images composed of 29322pixels) generic paint programs or (for drawings) some widely available 29323drawing editor, and that is suitable for input to text formatters or 29324for automatic translation to a variety of formats suitable for input 29325to text formatters. A copy made in an otherwise Transparent file 29326format whose markup, or absence of markup, has been arranged to thwart 29327or discourage subsequent modification by readers is not Transparent. 29328An image format is not Transparent if used for any substantial amount 29329of text. A copy that is not "Transparent" is called @strong{Opaque}. 29330 29331Examples of suitable formats for Transparent copies include plain 29332ASCII without markup, Texinfo input format, LaTeX input format, SGML 29333or XML using a publicly available DTD, and standard-conforming simple 29334HTML, PostScript or PDF designed for human modification. Examples of 29335transparent image formats include PNG, XCF and JPG. Opaque formats 29336include proprietary formats that can be read and edited only by 29337proprietary word processors, SGML or XML for which the DTD and/or 29338processing tools are not generally available, and the 29339machine-generated HTML, PostScript or PDF produced by some word 29340processors for output purposes only. 29341 29342The "@strong{Title Page}" means, for a printed book, the title page itself, 29343plus such following pages as are needed to hold, legibly, the material 29344this License requires to appear in the title page. For works in 29345formats which do not have any title page as such, "Title Page" means 29346the text near the most prominent appearance of the work's title, 29347preceding the beginning of the body of the text. 29348 29349The "@strong{publisher}" means any person or entity that distributes 29350copies of the Document to the public. 29351 29352A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 29353title either is precisely XYZ or contains XYZ in parentheses following 29354text that translates XYZ in another language. (Here XYZ stands for a 29355specific section name mentioned below, such as "@strong{Acknowledgements}", 29356"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 29357To "@strong{Preserve the Title}" 29358of such a section when you modify the Document means that it remains a 29359section "Entitled XYZ" according to this definition. 29360 29361The Document may include Warranty Disclaimers next to the notice which 29362states that this License applies to the Document. These Warranty 29363Disclaimers are considered to be included by reference in this 29364License, but only as regards disclaiming warranties: any other 29365implication that these Warranty Disclaimers may have is void and has 29366no effect on the meaning of this License. 29367 29368@strong{2. VERBATIM COPYING} 29369 29370You may copy and distribute the Document in any medium, either 29371commercially or noncommercially, provided that this License, the 29372copyright notices, and the license notice saying this License applies 29373to the Document are reproduced in all copies, and that you add no other 29374conditions whatsoever to those of this License. You may not use 29375technical measures to obstruct or control the reading or further 29376copying of the copies you make or distribute. However, you may accept 29377compensation in exchange for copies. If you distribute a large enough 29378number of copies you must also follow the conditions in section 3. 29379 29380You may also lend copies, under the same conditions stated above, and 29381you may publicly display copies. 29382 29383@strong{3. COPYING IN QUANTITY} 29384 29385If you publish printed copies (or copies in media that commonly have 29386printed covers) of the Document, numbering more than 100, and the 29387Document's license notice requires Cover Texts, you must enclose the 29388copies in covers that carry, clearly and legibly, all these Cover 29389Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 29390the back cover. Both covers must also clearly and legibly identify 29391you as the publisher of these copies. The front cover must present 29392the full title with all words of the title equally prominent and 29393visible. You may add other material on the covers in addition. 29394Copying with changes limited to the covers, as long as they preserve 29395the title of the Document and satisfy these conditions, can be treated 29396as verbatim copying in other respects. 29397 29398If the required texts for either cover are too voluminous to fit 29399legibly, you should put the first ones listed (as many as fit 29400reasonably) on the actual cover, and continue the rest onto adjacent 29401pages. 29402 29403If you publish or distribute Opaque copies of the Document numbering 29404more than 100, you must either include a machine-readable Transparent 29405copy along with each Opaque copy, or state in or with each Opaque copy 29406a computer-network location from which the general network-using 29407public has access to download using public-standard network protocols 29408a complete Transparent copy of the Document, free of added material. 29409If you use the latter option, you must take reasonably prudent steps, 29410when you begin distribution of Opaque copies in quantity, to ensure 29411that this Transparent copy will remain thus accessible at the stated 29412location until at least one year after the last time you distribute an 29413Opaque copy (directly or through your agents or retailers) of that 29414edition to the public. 29415 29416It is requested, but not required, that you contact the authors of the 29417Document well before redistributing any large number of copies, to give 29418them a chance to provide you with an updated version of the Document. 29419 29420@strong{4. MODIFICATIONS} 29421 29422You may copy and distribute a Modified Version of the Document under 29423the conditions of sections 2 and 3 above, provided that you release 29424the Modified Version under precisely this License, with the Modified 29425Version filling the role of the Document, thus licensing distribution 29426and modification of the Modified Version to whoever possesses a copy 29427of it. In addition, you must do these things in the Modified Version: 29428 29429 29430@enumerate A 29431 29432@item 29433Use in the Title Page (and on the covers, if any) a title distinct 29434from that of the Document, and from those of previous versions 29435(which should, if there were any, be listed in the History section 29436of the Document). You may use the same title as a previous version 29437if the original publisher of that version gives permission. 29438 29439@item 29440List on the Title Page, as authors, one or more persons or entities 29441responsible for authorship of the modifications in the Modified 29442Version, together with at least five of the principal authors of the 29443Document (all of its principal authors, if it has fewer than five), 29444unless they release you from this requirement. 29445 29446@item 29447State on the Title page the name of the publisher of the 29448Modified Version, as the publisher. 29449 29450@item 29451Preserve all the copyright notices of the Document. 29452 29453@item 29454Add an appropriate copyright notice for your modifications 29455adjacent to the other copyright notices. 29456 29457@item 29458Include, immediately after the copyright notices, a license notice 29459giving the public permission to use the Modified Version under the 29460terms of this License, in the form shown in the Addendum below. 29461 29462@item 29463Preserve in that license notice the full lists of Invariant Sections 29464and required Cover Texts given in the Document's license notice. 29465 29466@item 29467Include an unaltered copy of this License. 29468 29469@item 29470Preserve the section Entitled "History", Preserve its Title, and add 29471to it an item stating at least the title, year, new authors, and 29472publisher of the Modified Version as given on the Title Page. If 29473there is no section Entitled "History" in the Document, create one 29474stating the title, year, authors, and publisher of the Document as 29475given on its Title Page, then add an item describing the Modified 29476Version as stated in the previous sentence. 29477 29478@item 29479Preserve the network location, if any, given in the Document for 29480public access to a Transparent copy of the Document, and likewise 29481the network locations given in the Document for previous versions 29482it was based on. These may be placed in the "History" section. 29483You may omit a network location for a work that was published at 29484least four years before the Document itself, or if the original 29485publisher of the version it refers to gives permission. 29486 29487@item 29488For any section Entitled "Acknowledgements" or "Dedications", 29489Preserve the Title of the section, and preserve in the section all 29490the substance and tone of each of the contributor acknowledgements 29491and/or dedications given therein. 29492 29493@item 29494Preserve all the Invariant Sections of the Document, 29495unaltered in their text and in their titles. Section numbers 29496or the equivalent are not considered part of the section titles. 29497 29498@item 29499Delete any section Entitled "Endorsements". Such a section 29500may not be included in the Modified Version. 29501 29502@item 29503Do not retitle any existing section to be Entitled "Endorsements" 29504or to conflict in title with any Invariant Section. 29505 29506@item 29507Preserve any Warranty Disclaimers. 29508@end enumerate 29509 29510If the Modified Version includes new front-matter sections or 29511appendices that qualify as Secondary Sections and contain no material 29512copied from the Document, you may at your option designate some or all 29513of these sections as invariant. To do this, add their titles to the 29514list of Invariant Sections in the Modified Version's license notice. 29515These titles must be distinct from any other section titles. 29516 29517You may add a section Entitled "Endorsements", provided it contains 29518nothing but endorsements of your Modified Version by various 29519parties---for example, statements of peer review or that the text has 29520been approved by an organization as the authoritative definition of a 29521standard. 29522 29523You may add a passage of up to five words as a Front-Cover Text, and a 29524passage of up to 25 words as a Back-Cover Text, to the end of the list 29525of Cover Texts in the Modified Version. Only one passage of 29526Front-Cover Text and one of Back-Cover Text may be added by (or 29527through arrangements made by) any one entity. If the Document already 29528includes a cover text for the same cover, previously added by you or 29529by arrangement made by the same entity you are acting on behalf of, 29530you may not add another; but you may replace the old one, on explicit 29531permission from the previous publisher that added the old one. 29532 29533The author(s) and publisher(s) of the Document do not by this License 29534give permission to use their names for publicity for or to assert or 29535imply endorsement of any Modified Version. 29536 29537@strong{5. COMBINING DOCUMENTS} 29538 29539You may combine the Document with other documents released under this 29540License, under the terms defined in section 4 above for modified 29541versions, provided that you include in the combination all of the 29542Invariant Sections of all of the original documents, unmodified, and 29543list them all as Invariant Sections of your combined work in its 29544license notice, and that you preserve all their Warranty Disclaimers. 29545 29546The combined work need only contain one copy of this License, and 29547multiple identical Invariant Sections may be replaced with a single 29548copy. If there are multiple Invariant Sections with the same name but 29549different contents, make the title of each such section unique by 29550adding at the end of it, in parentheses, the name of the original 29551author or publisher of that section if known, or else a unique number. 29552Make the same adjustment to the section titles in the list of 29553Invariant Sections in the license notice of the combined work. 29554 29555In the combination, you must combine any sections Entitled "History" 29556in the various original documents, forming one section Entitled 29557"History"; likewise combine any sections Entitled "Acknowledgements", 29558and any sections Entitled "Dedications". You must delete all sections 29559Entitled "Endorsements". 29560 29561@strong{6. COLLECTIONS OF DOCUMENTS} 29562 29563You may make a collection consisting of the Document and other documents 29564released under this License, and replace the individual copies of this 29565License in the various documents with a single copy that is included in 29566the collection, provided that you follow the rules of this License for 29567verbatim copying of each of the documents in all other respects. 29568 29569You may extract a single document from such a collection, and distribute 29570it individually under this License, provided you insert a copy of this 29571License into the extracted document, and follow this License in all 29572other respects regarding verbatim copying of that document. 29573 29574@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29575 29576A compilation of the Document or its derivatives with other separate 29577and independent documents or works, in or on a volume of a storage or 29578distribution medium, is called an "aggregate" if the copyright 29579resulting from the compilation is not used to limit the legal rights 29580of the compilation's users beyond what the individual works permit. 29581When the Document is included in an aggregate, this License does not 29582apply to the other works in the aggregate which are not themselves 29583derivative works of the Document. 29584 29585If the Cover Text requirement of section 3 is applicable to these 29586copies of the Document, then if the Document is less than one half of 29587the entire aggregate, the Document's Cover Texts may be placed on 29588covers that bracket the Document within the aggregate, or the 29589electronic equivalent of covers if the Document is in electronic form. 29590Otherwise they must appear on printed covers that bracket the whole 29591aggregate. 29592 29593@strong{8. TRANSLATION} 29594 29595Translation is considered a kind of modification, so you may 29596distribute translations of the Document under the terms of section 4. 29597Replacing Invariant Sections with translations requires special 29598permission from their copyright holders, but you may include 29599translations of some or all Invariant Sections in addition to the 29600original versions of these Invariant Sections. You may include a 29601translation of this License, and all the license notices in the 29602Document, and any Warranty Disclaimers, provided that you also include 29603the original English version of this License and the original versions 29604of those notices and disclaimers. In case of a disagreement between 29605the translation and the original version of this License or a notice 29606or disclaimer, the original version will prevail. 29607 29608If a section in the Document is Entitled "Acknowledgements", 29609"Dedications", or "History", the requirement (section 4) to Preserve 29610its Title (section 1) will typically require changing the actual 29611title. 29612 29613@strong{9. TERMINATION} 29614 29615You may not copy, modify, sublicense, or distribute the Document 29616except as expressly provided under this License. Any attempt 29617otherwise to copy, modify, sublicense, or distribute it is void, and 29618will automatically terminate your rights under this License. 29619 29620However, if you cease all violation of this License, then your license 29621from a particular copyright holder is reinstated (a) provisionally, 29622unless and until the copyright holder explicitly and finally 29623terminates your license, and (b) permanently, if the copyright holder 29624fails to notify you of the violation by some reasonable means prior to 2962560 days after the cessation. 29626 29627Moreover, your license from a particular copyright holder is 29628reinstated permanently if the copyright holder notifies you of the 29629violation by some reasonable means, this is the first time you have 29630received notice of violation of this License (for any work) from that 29631copyright holder, and you cure the violation prior to 30 days after 29632your receipt of the notice. 29633 29634Termination of your rights under this section does not terminate the 29635licenses of parties who have received copies or rights from you under 29636this License. If your rights have been terminated and not permanently 29637reinstated, receipt of a copy of some or all of the same material does 29638not give you any rights to use it. 29639 29640@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29641 29642The Free Software Foundation may publish new, revised versions 29643of the GNU Free Documentation License from time to time. Such new 29644versions will be similar in spirit to the present version, but may 29645differ in detail to address new problems or concerns. See 29646@indicateurl{http://www.gnu.org/copyleft/}. 29647 29648Each version of the License is given a distinguishing version number. 29649If the Document specifies that a particular numbered version of this 29650License "or any later version" applies to it, you have the option of 29651following the terms and conditions either of that specified version or 29652of any later version that has been published (not as a draft) by the 29653Free Software Foundation. If the Document does not specify a version 29654number of this License, you may choose any version ever published (not 29655as a draft) by the Free Software Foundation. If the Document 29656specifies that a proxy can decide which future versions of this 29657License can be used, that proxy's public statement of acceptance of a 29658version permanently authorizes you to choose that version for the 29659Document. 29660 29661@strong{11. RELICENSING} 29662 29663"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 29664World Wide Web server that publishes copyrightable works and also 29665provides prominent facilities for anybody to edit those works. A 29666public wiki that anybody can edit is an example of such a server. A 29667"Massive Multiauthor Collaboration" (or "MMC") contained in the 29668site means any set of copyrightable works thus published on the MMC 29669site. 29670 29671"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 29672license published by Creative Commons Corporation, a not-for-profit 29673corporation with a principal place of business in San Francisco, 29674California, as well as future copyleft versions of that license 29675published by that same organization. 29676 29677"Incorporate" means to publish or republish a Document, in whole or 29678in part, as part of another Document. 29679 29680An MMC is "eligible for relicensing" if it is licensed under this 29681License, and if all works that were first published under this License 29682somewhere other than this MMC, and subsequently incorporated in whole 29683or in part into the MMC, (1) had no cover texts or invariant sections, 29684and (2) were thus incorporated prior to November 1, 2008. 29685 29686The operator of an MMC Site may republish an MMC contained in the site 29687under CC-BY-SA on the same site at any time before August 1, 2009, 29688provided the MMC is eligible for relicensing. 29689 29690@strong{ADDENDUM: How to use this License for your documents} 29691 29692To use this License in a document you have written, include a copy of 29693the License in the document and put the following copyright and 29694license notices just after the title page: 29695 29696@quotation 29697 29698Copyright © YEAR YOUR NAME. 29699Permission is granted to copy, distribute and/or modify this document 29700under the terms of the GNU Free Documentation License, Version 1.3 29701or any later version published by the Free Software Foundation; 29702with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 29703A copy of the license is included in the section entitled "GNU 29704Free Documentation License". 29705@end quotation 29706 29707If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 29708replace the "with ... Texts." line with this: 29709 29710@quotation 29711 29712with the Invariant Sections being LIST THEIR TITLES, with the 29713Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 29714@end quotation 29715 29716If you have Invariant Sections without Cover Texts, or some other 29717combination of the three, merge those two alternatives to suit the 29718situation. 29719 29720If your document contains nontrivial examples of program code, we 29721recommend releasing these examples in parallel under your choice of 29722free software license, such as the GNU General Public License, 29723to permit their use in free software. 29724 29725@node Index,,GNU Free Documentation License,Top 29726@unnumbered Index 29727 29728 29729@printindex ge 29730 29731 29732@c %**end of body 29733@bye 29734